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This manual is part of the AIRES 2.2.0 distribution. The AIRES system is distributed worldwide 
as "free software" for all scientists working in educational/research non-profit institutions. Users 
from commercial or non-educational institutions must obtain the author's written permission be- 
fore using the software and/or its related documentation. 

The present document makes obsolete all the previous versions of the AIRES user's manual and 
reference guide. 

NO WARRANTY. The AIRES system is provided in an "as is" basis, without warranty of any 
kind, either expressed or implied, including, but not limited to, the implied warranties of mer- 
chantability and fitness for a particular purpose. The entire risk as to the quality and performance 
of the program is with the user Should the program prove defective, the user assumes the cost 
of all necessary servicing, repair or correction. In no event will the AIRES author(s), be liable to 
any user for damages, including any general, special, incidental or consequential damages arising 
out of the use or inability to use the Simulation System (including, but not limited to, loss of data 
or data being rendered inaccurate or losses sustained by the user or third parties or a failure of 
the System to operate with any other programs), even if the author(s) have been advised of the 
possibility of such damages. 

Product and company names mentioned in this manual are trademarks or trade names of their 
respective companies. 



Summary 



The present version of AIRES (2.2.0) represents a new release of the Air Shower Simulation System 
where many new features and algorithm improvements have been added to it. The most important 
additions are: An improved parameterization of the electron and positron continuous energy losses; 
a resampling algorithm complements the thinning to achieve important reduction of the output com- 
pressed files; and a new interface for processing special primary particles not directly propagated by 
AIRES internal engine. 

It is important to mention that many of the algorithms for particle propagation included in the 
present release of the AIRES system are based on the corresponding procedures of the widely known 
MOCCA program developed by A. M. Hillas. MOCCA has been the primary reference used to de- 
velop the first version of AIRES (1.2.0, May 1997). As a consequence, results coming from this first 
version are concordant with MOCCA's output when invoked with similar initial conditions. Later ver- 
sions of AIRES do include procedures independently developed and so a strict equivalence between 
both programs is no longer maintained. 

The changes from the previous version (2.0.0, April 1999) can be summarized as follows: 

• An improved parameterization of the curves for electron and positron losses in air. 

• A resampling algorithm which selectively saves particles located near the shower axis, capable 
of reducing substantially the sizes of the compressed particle files. 

• An improvement in the algorithm to process lambda baryons generated by QGSJET. A related 
bug affecting noticeably about 1% of the showers has been fixed. 

• The AIRES kernel is now capable of invoking external, user-written, programs to generate 
sets of particles to be injected in the stacks before starting the simulation of the corresponding 
shower. This kind of primary particle processing, called special primary particles was devel- 
oped for several purposes, for example, processing the first interaction of exotic primaries like 
neutrinos, including all the particles generated by ultra-high energy gamma ray conversion in 
the geomagnetic field before reaching the atmosphere, etc. 

• Upgraded version of QGSJET. 

• Important extension of the AIRES object library, including a series of utilities to process special 
primaries. 
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SUMMARY 



• Additionally, lots of minor changes, improvements, and -of course- corrections of bugs! 

Many of the developments presented for the current release were performed taking into account 
users' suggestions and remarks. The author is indebted to everybody that have contacted him (a very 
long list of persons indeed), either to report a bug or to make a comment on the program. 

The present summary does not include additional information about AIRES and its main features. 
We have instead decided to include the summary of version 1.4.2 in the present edition of the user's 
manual, so the interested reader may consult there the main features and history of the AIRES air 
shower simulation system. 

As mentioned in the summary of version 1.4.2, every new release of AIRES represents a new step 
towards a complete and most reliable air shower simulation system. But it must be understood that 
still there are many things pending implementation. We can include in such category, for example, 
alternative atmospheric models, generation of fluorescence and Cerenkov photons, compressed read 
and write routines, etc. The development continues, and the mentioned features will be progressively 
incorporated in future releases of AIRES. 



La Plata, November 1999. 



Summary of version 1.4.2 



The name AIRES (AIR-shower Extended Simulations) identifies a set of programs and subroutines 
to simulate particle showers produced after the incidence of high energy cosmic rays on the Earth's 
atmosphere, and to manage all the related output data. 

The physical algorithms currently used in AIRES main simulation programs are based on the 
corresponding procedures of the widely known MOCCA program developed by A. M. Hillas. The 
MOCCA program constitutes an important milestone in the history of air shower simulations. It 
has been used successfully to interpret data coming from several air shower experiments and its 
calculating engine allows to perform simulations in a wide range of primary energies with a moderate 
consumption of computer resources. 

MOCCA has been the primary reference used to develop the first version of AIRES (1.2.0). As 
a consequence, results coming from this program are concordant with MOCCA's output when in- 
voked with similar initial conditions. Later versions of AIRES do include procedures independently 
developed and so a strict equivalence between both programs is no longer maintained. 

The AIRES simulation system provides a comfortable environment where to perform reliable 
simulations taking advantage of present day computer technology and using the extensive knowl- 
edge on shower processes that is contained in MOCCA's source code: The Input Directive Language 
(IDL) is a set of simple directives which allow for an efficient control of the input parameters of the 
simulation. The AIRES Runner System is a powerful tool to manage long simulation tasks in UNIX 
environments, allowing the user to coordinate several tasks running concurrently, controlling the evo- 
lution of a given job while running, etc. The AIRES summary program processes the internal dump 
files generated by the main simulation program, and allows to obtain data related with physical ob- 
servables either after or during the simulations. Finally, the AIRES object library provides a series 
of auxiliary routines to process the data generated by the simulation program, in particular the data 
contained in the compressed output files, the detailed particle data files containing per-particle infor- 
mation for particles reaching the ground, crossing different observing levels during their evolution, 
etc. 

The purpose of this User's guide and reference manual is to give a detailed description of the 
simulating system, how to control the simulation parameters and how to analyze the output data. 

The particles taken into account in the simulations are: Gammas, electrons, positrons, muons, pi- 
ons, nucleons and antinucleons, and nuclei up to Z = 26. Electron and muon neutrinos are generated 
in certain processes (decays) and accounted for their energy, but not propagated. The primary particle 
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can be any one of the already mentioned particles, with energy ranging from several GeV up to more 
than 1 ZeV (lO^^ eV). 

Among all the physical processes that may undergo the shower particles, the most important 
from the probabilistic point of view are taken into account in the simulations. Such processes are: 
(i) Electrodynamical processes: Pair production and electron-positron annihilation, bremsstrahlung 
(electrons and positrons), knock-on electrons {6 rays), Compton and photoelectric effects, Landau- 
Pomeranchuk-Migdal (LPM) effect and dielectric suppression, (ii) Unstable particle decays, pions 
and muons, for instance, (iii) Hadronic processes: Inelastic collisions hadron-nucleus and photon- 
nucleus, sometimes simulated using an external package which implements a given hadronic inter- 
action model (see below). Photonuclear reactions. Nuclear fragmentation, elastic and inelastic, (iv) 
Propagation of charged particles: Losses of energy in the medium (ionization), multiple Coulomb 
scattering and geomagnetic deflections. 

With the exception of dielectric suppression, this selection of processes comes directly from 
MOCCA and, as indicated previously, most of the algorithms used to simulate them are similar- to 
the coiTesponding ones used in that program. It is worthwhile mentioning that AIRES first version 
does not include all the procedures contained in MOCCA: Several MOCCA features like scintillator 
simulation or generation of Cerenkov light are not included in AIRES. 

The current version of AIRES (2.2.0) includes many improvements with respect to the first version 
(1.2.0). Among all these changes, the most important are: 

• The spherical shape of the Earth is taken into account. This, together with improved shower 
geometry algorithms permits safe operation at all zenith angles. It is important to remark that 
there is no significant increase in computer time requirements associated with these new pro- 
cedures. 

• The geomagnetic field is taken into account when propagating charged particles. The user can 
set the field strength and orientation either manually or by means of an auxiliary model (The 
International Geomagnetic Reference Field, IGRF) entering the geographical coordinates of 
the corresponding site. Fluctuations in the magnetic field can also be introduced. 

• The well-known QGSJET hadronic interactions model was installed and can be invoked as an 
alternative to the SIBYLL model implemented in the previous version. This is an important 
difference with MOCCA which presently has no link to QGSJET. 

• The algorithms related with the LPM effect were rewritten. The new procedures emulate 
Migdal's theory, taking also into account the effect of dielectric suppression. 

• The procedures for electron-positron bremsstrahlung and pair production were thoroughly re- 
vised and improved. 

• An improved algorithm for the estimation of the shower maximum is included. It is based on 
4-parameter nonlinear least squares fits using the Gaisser-Hillas function to model the longitu- 
dinal profile of the shower. 
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• The AIRES object library was substantially expanded, including a C interface which allows 
processing AIRES compressed output files from a C or C++ environment. 

After the release of the first public version of AIRES, in May 1997, groups from institutions 
around the world started using the softwai^e to perform different kinds of air shower simulations. 
Thanks to all the users' comments received it was possible to identify several problems that were 
present in that version. All the queries were solved, and most comments suggesting new features for 
the program were taken into account when preparing the present version. 

Receiving feedback from the users not only demonstrates that the software is indeed being used, 
but also helps to make every new version more powerful and reliable than the previous one. The author 
is indebted to everybody that have contacted him, either to report a bug or to suggest a modification 
in the code, in particular to the group colleagues at the Department of Physics at the Universidad 
de La Plata: A. Cillis, M. T. Dova, L. N. Epele, H. Fanchiotti and C. A. Garcia Canal; also to I. 
Albuquerque (U. of Chicago, USA), M. Berger and A. Dzierba (U. of Indiana, USA), X. Bertou and 
P. Billoir (LPNHE, France), C. Celestino Silva (Campinhas, Brazil), D. Heck, K.-H. Kampert and 
J. Knapp (Karlsruhe, Germany), L. Nellen (UNAM, Mexico), and R. Vazquez (Sao Paulo, Brazil). 
Useful comments from J. W. Cronin and C. Hojvat are also acknowledged. 

Even if the present release of AIRES represents an important step towards a complete and most re- 
liable air shower simulation program, it must be mentioned that there are still many non-implemented 
things like alternative atmospheric models, a more complete set of physical interactions including, 
for example, kaon tracking, generation of fluorescence and Cerenkov photons, etc. It is planned to 
progressively incorporate such features in future releases of AIRES. 



La Plata, June 1998. 
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Chapter 1 

Introduction 



Cosmic rays with energies larger than 100 TeV must be studied -at present- using experimental 
devices located on the surface of the Earth. This implies that such kind of cosmic rays cannot be 
detected directly; it is necessary instead to measure the products of the atmospheric cascades of 
particles initiated by the incident astroparticle. An atmospheric particle shower begins when the 
primary cosmic particle interacts with the Earth's atmosphere. This is, in general, an inelastic nucleai^ 
collision that generates a number of secondary particles. Those particles continue interacting and 
generating more secondary particles which in turn interact again similarly as their predecessors. This 
multiplication process continues until a maximum is reached. Then the shower attenuates as far as 
more and more particles fall below the threshold for further particle production. 

A detailed knowledge of the physics involved is thus necessary to interpret adequately the mea- 
sured observables and be able to infer the properties of the primary particles. This is a complex 
problem involving many aspects: Interactions of high energy particles, properties of the atmosphere 
and the geomagnetic field, etc. Computer simulation is one of the most convenient tools to quantita- 
tively analyze such particle showers. 

In the case of air showers initiated by ultra-high energy astroparticles (E > 10^^ eV), the primary 
particles have energies that are several orders of magnitude lai^ger than the maximum energies attain- 
able in experimental colliders. This means that the models used to rule the behavior of such energetic 
particles must necessarily make extrapolations from the data available at much lower energies, and 
there is still no definitive agreement about what is the most convenient model to accept among the 
several available ones. 

The AIRES systemQis a set of programs to simulate such air showers. One of the basic objectives 
considered during the development of the software is that of designing the program modulai^ly, in 
order to make it easier to switch among the different models that are available, without having to get 
attached to a particular one. 

Several simulation programs that were developed in the past were studied in detail in order to 
gain experience and improve the new design. Among such programs, the well-known MOCCA 

'aires is an acronym for AIR - shower Extended Simulations. 
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code created by A. M. Hillas occupies an outstanding position: It has been successfully used 
to interpret data coming from various air shower experiments, can be operated in a wide range of 
primary energies (from 10^^ eV to 10^*^ eV), and permits to perform simulations with a relatively 
moderate consumption of computer resources. 

The MOCCA program has been extensively used as the primary reference when developing the 
first version of AIRES released in May 1997. The physical algorithms of AIRES 1.2.0 are virtually 
equivalent to the corresponding ones from MOCCA [||]. The structure of AIRES is designed to take 
advantage of present day computers, and therefore the new program represents an improvement of 
the MOCCA code, allowing the user to comfortably perform simulations based on the extensive 
knowledge on air shower processes that is contained in MOCCA's source lines. 

It is important to remark, however, that the present version of AIRES does include modifications 
to the original algorithms which can alter the program's output with respect to that from MOCCA. 
This implies that both programs are no longer strictly equivalent, even if AIRES 's physical algorithms 
continue to be largely based on MOCCA's. 

Another characteristic of ultra-high energy simulations that was taken into account when develop- 
ing AIRES is the large number of particles involved. For example, a 10^*^ eV shower contains about 
10^^ secondary particles. From the computational point of view, this fact has two main consequences 
that were specially considered at the moment of designing AIRES: (i) With present day comput- 
ers, it is virtually impossible to follow all the generated particles, and therefore a suitable sampling 
technique must be used to reduce the number of particles actually simulated. The so-called thin- 
ning algorithm introduced by Hillas [Q] or the sampling algorithm of Kobal, Filipcic and Zavrtanik 

represent examples of such sampling methods, (ii) The simulation algorithm is CPU intensive, 
and therefore it is necessary to develop a series of special procedures that will provide an adequate 
environment to process computationally long tasks. 

There are many quantities that define the initial or environmental conditions for an air shower, 
for example, the identity of the primary particle and its energy, the position of the ground surface, 
the minimum energy a particle must have to be taken into account in the simulation, the intensity and 
orientation of the geomagnetic field, etc. Additionally, it is possible to define many observables that 
are useful to characterize the particle shower, namely, longitudinal and lateral distribution of particles, 
energy distributions, position of the shower maximum and so on. 

A comfortable environment is provided by AIRES to manage all the input and output data: The 
Input Directive Language (IDL) is a set of human-readable input directives that allow the user to ef- 
ficiently steer the simulations. The AIRES summary program and the AIRES object library represent 
a set of tools to manage the output data after the simulations are finished, and even during them, 
allowing to control their evolution. Data associated with particles reaching ground or crossing prede- 
termined observing levels can be recorded into compressed output files. A special data compression 
procedure is used to reduce as much as possible the size of the files, which tends to be very large in 
certain circumstances. The compressed files can be processed with the help of some auxiliary routines 
that are included in the AIRES library. The machine and operating system used to generate such files 
may be different that the ones used to read them. 
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As mentioned previously, the physical algorithms of the MOCCA simulation program developed 
by A. M. Hillas were used as the primary reference in the original design of AIRES. As a result, 
the output data coming from MOCCA SP (1996)0 (mocorbin_zg) and AIRES first version (1.2.0) ^ 
are similar when both programs are invoked with equivalent initial conditions^ 

The particles taken into account by AIRES in the simulations are: Gammas, electrons, positrons, 
muons, pions, kaons, eta mesons, nucleons, antinucleons, and nuclei up to Z = 26. Electron and 
muon neutrinos are generated in certain processes (decays) and accounted for their energy, but not 
propagated. The primary particle can be any one of the already mentioned particles, with energy 
ranging from several GeV up to more than 1 ZeV (10^^ eV). It is also possible to simulate showers 
initiated by "special" primary particles via a call to a user-written module capable of processing the 
"first interaction" of the primary and returning a hst of standard particles suitable for being processed 



by AIRES. A detailed description on how to define and use special primaries is placed in section 

Among all the physical processes that may undergo the shower particles, the most important 
from the probabilistic point of view are taken into account in the simulations. Such processes are: 
(i) Electrodynamical processes: Pair production and electron-positron annihilation, bremsstrahlung 
(electrons and positrons), knock-on electrons {5 rays), Compton and photoelectric effects, Landau- 
Pomeranchuk-Migdal (LPM) effect and dielectric suppression, (ii) Unstable particle decays, pions 
and muons, for instance, (iii) Hadronic processes: Inelastic collisions hadron-nucleus and photon-nu- 
cleus, sometimes simulated using an external package which implements a given hadronic interaction 
model. Photonuclear reactions. Nuclear fragmentation, elastic and inelastic, (iv) Propagation of 
charged particles: Losses of energy in the medium (ionization), multiple Coulomb scattering and 
geomagnetic deflections. 

All the general characteristics of AIRES and the physics involved in air shower simulations are 
described in more detail in chapter ^. 

There ai^e several improvements that differentiate the current AIRES version (2.2.0) with respect 
to the previous one (2.0.0, April 1 



An improved parameterization of the curves for electron and positron losses in air. 

A resampling algorithm which selectively saves particles located near the shower axis, capable 
of reducing substantially the sizes of the compressed particle files. 

An improvement in the algorithm to process lambda baryons generated by QGSJET [^]. A 
related bug affecting noticeably about 1 % of the showers has been fixed. 

The AIRES kernel is now capable of invoking external, user-written, programs to generate 
sets of particles to be injected in the stacks before starting the simulation of the corresponding 



^MOCCA SP is a newer version of tlie MOCCA program whiclr incorporates some improvements witli respect to tlie 
original version developed by A. M. Hillas. 

^ AIRES and MOCCA input parameter sets are different, and therefore initial conditions that are equivalent for both 
programs can be accomplished only in selected particular cases. 

""For detailed information about the previous version of AIRES see reference [n]. 
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shower. This kind of primary particle processing, called special primary particles was devel- 
oped for several purposes, for example, processing the first interaction of exotic primaries like 
neutrinos, including all the particles generated by ultra-high energy gamma ray conversion in 
the geomagnetic field before reaching the atmosphere, etc. 

• Upgraded version of QGSJET [0]. 

• Important extension of the AIRES object library, including a series of utilities to process special 
primaries. 

• Additionally, lots of minor changes, improvements, and -of course- corrections of bugs! 

AIRES is completely written in standard FORTRAN 77 (using a few extensions that are, to the 
best of our knowledge, accepted by all FORTRAN compilers). The complete AIRES 2.2.0 source 
code, which includes the QGSJEI^ [0] and SIBYLL| ^ hadronic colhsions packages, the IGRF ^ 
routines to evaluate geomagnetic data and Netlib/minpack/lmder nonlinear least squares fitting pack- 
age [|^], consists of more than 590 routines, adding up to more than 80,000 source lines extensively 
commented. 

In the present version, the AIRES simulation system consists of the following: 

• The main air shower simulation programs. Aires and AiresQ, containing the interfaces with 
the hadronic collision packages SIBYLL and QGSJET respectively. 

• The summary program (AiresSry) designed to process a part of the data generated by the 
simulation programs, allowing the user to analyze the results of the simulation after completing 
it, or even while it is being run. 

• The IDF to ADF file format converting program AiresIDF2ADF. 

• A library of utilities to help the user to process the compressed output data files generated by 
the simulation program, write external modules to process special primaries, etc. In UNIX 
environments this library is implemented as an object library called libAires.a. 

• The AIRES runner system: A set of shell scripts to ease working with AIRES in UNIX envi- 
ronments. 



A series of PAW [11] macros capable of downloading AIRES output data directly from within 



this analysys program. 



^The version of QGSJET installed in AIRES 2.2.0 is dated 25/Mar/1999. 
*The version of SIBYLL installed in AIRES 2.2.0 is dated 16/ Apr/1997. 
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1.1 Structure of the main simulation programs 

An air shower starts when a cosmic particle reaches the Earth's atmosphere and interacts with it. 
In most cases the first interaction is an inelastic collision of the (high energy) primary particle with 
an air nucleus. The product of this collision is a set of secondary particles carrying a fraction of 
the primary's energy. These secondaries begin to move through the atmosphere and will eventually 
interact similarly as the primary did, generating new sets of secondaries. This multiplication process 
continues until a maximum is reached. After that moment the shower begins to attenuate because an 
increasing number of secondaries ar^e produced with energies too low for further particle generation. 
This phenomenon is simulated in AIRES in the following way: 

1. Several data arrays or stacks are defined. Every record within any stacks is a particle entry, and 
represents a physical particle. The data contained in every record are related to the characteris- 
tics of the corresponding particle: Identity, position, energy, etc. 

2. The particles can move inside a volume within the atmosphere where the shower takes place. 
This volume is limited by the ground, and injection surfaces, and by vertical planes which limit 
the region of interest. 

3. Before starting the simulations all the stacks are empty. The first action is to add the first stack 
entry, which corresponds to the primary particle. The primary is initially located at the injection 
surface, and its downwards direction of motion defines the sower axis. 

4. The stack entries are repeatedly processed sequentially. Every particle entry is updated analyz- 
ing first all the possible interactions it can have, and evaluating the corresponding probabilities 
for each possibility, taking into account the physics involved. 

5. Using a stochastic method, the mentioned probabilities are used to select one of the possible 
interactions. This selection defines what is going to happen with the corresponding particle at 
that moment. 

6. The interaction is processed: First the particle is moved a certain distance (which comes out 
from the mentioned stochastic method), then the products of the interaction are generated. New 
stack entries are appended to the existing lists for every one of the secondary particles that are 
created. Depending on the particular interaction that is being processed, the original particle 
may survive (the corresponding entry remains in the stack for further processing) or not (the 
entry is deleted). 

7. When a charged particle is moved, its energy is modified to take into account the energy losses 
in the medium (ionization). 

8. Particle entries can also be removed when one of the following events happens: (a) The energy 
of the particle is lower than a certain threshold energy called cut energy. The cut energies may 
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be different for different particle kinds, (b) The particle reaches ground level, (c) A particle 
going upwards reaches the injection surface, (d) A particle with quasi-horizontal motion exits 
the region of interest. 

9. After having scanned all the stacks, it is checked whether or not there are remaining particle 
entries pending further processing. If the answer is positive, then all the stacks are re-scanned 
once more; otherwise the simulation of the shower is complete. 

The group of algorithms related with interaction selection and processing, as well as calculation 
of energy losses is the group of physical algorithms. In the current version of AIRES such algorithms 
are mostly equivalent to the ones implemented in the program MOCCA [|T]]. 

The most important air shower observables are those related with statistical distributions of par- 
ticle properties. To evaluate such quantities the simulation engine of AIRES also possesses internal 
monitoring procedures that constantly check and record particles reaching ground and/or passing 
across predetermined observing surfaces located between the ground and injection levels. 

From this description, it shows up clearly that the air shower simulation programs consist of 
various interacting procedures that operate on a data set with a variable number of records, modifying 
its contests, increasing or decreasing its size accordingly with predetermined rules. 

It is necessary to do a modular design of such a program to make it more manageable; and this 
is particularly relevant for the case of the algorithms related with the physical laws that rule the 
interactions where -as mentioned- there are still open problems requiring continuous change and 
testing of procedures. 

Figure |0] contains a schematic representation of the modular structure of the main simulation 
programs. Every unit consists of a set of subroutines performing the tasks assigned to the correspond- 
ing unit. In general, every unit can be replaced virtually without altering the other ones. In the case of 
the external interaction models where complete packages developed by other groups are linked to the 
simulation program via a few interface routines, the modularity acquires particular importance since 
it makes it possible to easily switch among the various packages available. 

The user controls the simulation parameters by means of input directives. The Input Directive 
Language (IDL) is a set of human-readable directives than provides a comfortable environment for 
task control. After the input data is processed and checked, control is transferred to the program's 
kernel. During the simulations the particles of the cascade are generated and processed by several 
packages. The interactions model package contains the "physics" of the problem. 

The job control unit is responsible (among other tasks) of updating the internal dump file (IDF). 
This file contains all the relevant internal data used during the simulation, and is the key for system 
fault tolerant processing since it makes it possible to restart a broken simulation process from the last 
update of the IDF. 

The kernel interacts also with other modules that generate the output data, namely, log and sum- 
mary files, internal dump file -in either binary or ASCII (portable) format- and compressed output 
files generated by the monitoring routines and the particle data output unit. 
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Figure 1.1. The structure of AIRES main simulation program. 
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In the current version of AIRES, there are two compressed output files implemented: The ground 
particle file and the longitudinal tracking particle file. Records within the ground particle file (longitu- 
dinal tracking file) contain data related with particles reaching ground level (passing across observing 
levels). 

Since the number of data records contained in such files can be enormous, a special compression 
mechanism has been developed to reduce file size requirements. The compressing algorithm is pait 
of the particle data output module. To give an idea of the space needed to store the particle records, 
let us consider the case of the ground particle file with its default settings: For each paiticle reaching 
ground and fulfilling certain (user settable) conditions, a 18 byte long record is written. The record 
data items are: particle identity, statistical weight, position, time of arrival and direction of motion. 
Leading and trailing records are written before and after an individual shower is completely simulated. 
Considering, for instance, a "hard" simulation regime where 2 x 10^^ eV primary energy showers 
(proton or iron) are simulated with 10~^ relative thinning level using the standard Hillas algorithm 



(see section |2.3| ), generate a compressed ground paiticle file of size less than 1 1 MB/shower when 
storing all the particles whose distance from the shower core is larger than 50 m and less than 12 km. 

The green unit named "special primaries" consists basically in a kernel-operated interface with 
user-provided external modules capable of generating lists of particles that will be used to initiate a 
shower. This feature allows the user to start showers initiated by non-conventional (exotic) primary 
particles like neutrinos, for example. 

The math and physical data routines aie called from several units within the program and provide 
many utility calculations. In particular, they contain the atmospheric model (used to account for 
the varying density of the Earth's atmosphere) and the geomagnetic field auxiliary routines that can 
evaluate the geomagnetic field in any place around the world. 

1.2 Computer requirements 

The computer requirements to simulate air showers largely depend upon the characteristics of each 
particular task. In particular, CPU time requirements can be very hard, specially when the simulations 
are done using low thinning energies (For example, -Etiunning ^ 10"''^ ^'primary) 



Using the Hillas thinning algorithm (see section |2.3.1| ), and considering the representative case of 
5 X 10^^ eV proton showers with 40 deg zenith angle, it is easy to verify that the CPU time per shower 
scales linearly with log(£'primary/^'thinning)- The CPU time per shower increases roughly in a factor 
of 8 when -EprimaryZ-Ethinning is increased in one order of magnitude. To give an estimation of the ab- 
solute amount of time needed to simulate one shower, it can be mentioned that in a Pentium II machine 
(300 Mhz clock) using Linux OS the CPU time for a single shower with -EprimaryZ-Sthinning = 10^ is 
about 12 minutes. This projects onto some 12 and 100 hours for 10^ and 10*^ respectively. 

The CPU time depends on other parameters besides the thinning and primary energies (see section 



2.3. 3[ ). The inclination of the shower axis (zenith angle) is one of them. The CPU time per shower 



generally increases when the zenith angle is enlarged: A 45 deg (85 deg) inclined shower requires 
roughly 1.3 (1.6) times more CPU time that a vertical one. 
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It is important to say that the algorithms that take into account the curvature of the earth and the 
effect of the geomagnetic field were designed in such a way that their CPU time requirements are 
not important when compared with the overall requirements of the simulating engine. As a result, 
the CPU time per shower needed to perform simulations using the current AIRES version (2.2.0) are 
essentially the same as the corresponding ones of version 1.2.0, even for showers with large zenith 
angles where the spherical earth calculations become important [^]. 

Memory requirements depend basically upon the size of the stack ai^ea (set at compilation time). 
With the default area size of 5 MB (Megabytes), the program uses about 9 MB of random access 
memory. Disk storage requirements depend on the stack area size, thinning level, and (for the output 
compressed files) on the number and kind of showers to be simulated. Internal procedures create 
some scratch files whose size can be as large as several tens of MBQ The size of the largest scratch 



files is directly correlated to the total number of processed particles. In figure 1.2, the number of 
processed particles is plotted versus the thinning level. It is evident that the processed particles (and 
hence the hai"d disk space requirements) grows significantly when the thinning energy is lowered. 
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Figure 1.2. Number of 
processed stack entries 
(particles) as a function of the 
thinning level. The showers 
were initiated by 10^^ eV 
protons, with vertical 
incidence and ground level 
located at 1000 g/cm^. 



1.3 Getting and installing AIRES 



AIRES is distributed worldwide as "free software" for all scientists working in educational/research 
non-profit institutions. Users from commercial or non-educational institutions must obtain the au- 
thor's written permission before using the software. 

The present version of AIRES (2.2.0) can be obtained from the World Wide Web, at the following 
address: 



http: //www. f isica . unlp . edu . ar/auger/aires 



AIRES is distributed in the form of a compressed UNIX tar file. The installation is automatic for 
UNIX systems. For other operating systems some adaptive work may be needed. Appendix ^ (page 



103| ) contains detailed instructions on how to install AIRES and/or maintain an existing installation. 



'The scratch files can occupy about 100 MB in some extreme circumstances 



Chapter 2 

General characteristics of AIRES 



The aim of this chapter is to introduce the basic concepts needed to adequately define the problem 
being considered. 



2.1 The environment of an air shower 
2.1.1 Coordinate system 

The AIRES coordinate system is a Cartesian system whose origin is placed at sea level at a user- 
specified geographical location. The xy plane is located horizontally at sea level and the positive 
z-axis points upwards. The x-axis points to the "local" magnetic North, that is, the local direction of 



the horizontal component of the geomagnetic field (see section [2. 1.5| for details). The y-axis points to 
the West. 



Figure 2.1 shows an schematic representation of the coordinate system used by AIRES. The xy 
plane is tangent to the sea level surface, here taken as a spherical surface of radius Re = 6370949 
m centered at the Earth's center. The ground level, and the injection level, refer to spherical surfaces 
concentric to the sea level surface and intersecting the 2:-axis at z = {zg > 0) and z = Zi (zi > Zg) 
respectively. 

The shower axis of a shower with zenith angle is defined as the straight line that passes by 
the intersection point between the ground level and the z-axis, and makes an angle with the z-axis 
(0 < < 90°). The azimuth angle $ is the angle between the horizontal projection of the shower 
axis and the x-axis (0 < <I> < 360°). 

In AIRES version 1.2.0, all the spherical surfaces mentioned in the preceding paragraphs were 
approximated as planes. This approximation is justified every time the horizontal distances involved 
are negligible in comparison with the Earth's radius, iig. This is the case for showers whose zenith 
angle is small, but certainly not for those with large zenith angles, especially for quasi-horizontal 
showers. 

For AIRES version 1 .4.0 or later the curvature of the Earth is taken into account to make it possi- 
ble to reliably simulate showers with zenith angles in the full range < < 90°. Since full spherical 
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Earth" zone 
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Figure 2.1. AIRES coordinate system. 



calculations are computationally expensive, an effort was made to optimize the corresponding algo- 
rithms. These optimizations are based on two key concepts: (i) Even if a non- vertical shower can start 
in a very distant point, most of the shower development takes place relatively near the z-axis where 
the "plane Earth" approximation is acceptable, (ii) Many calculations that employ spherical geometry 
can be substantially simplified if the coordinate system is temporarily rotated so the involved point 
lies near the new z-axis, and plane geometry is used in the rotated system. If necessary, an inverse 
rotation is applied to express results in the original coordinate system. 

In order to apply the first concept, a zone where the Earth can be acceptably approximated as 
plane must be defined. As it will be justified later in this chapter (see section 2.1.4), the Earth's 
spherical shape can be ignored in a conic region region centered at the z-axis, with a varying diameter 
ranging from 8 km at sea level to 45 km at an altitude of 100 km.a.s.l. The average limits of that 



region (about 22 km diameter) ai^e indicated in figure 



To fastly perform the rotation operations needed to express coordinates and vector in a temporary 
local coordinate system, it results convenient to use a redundant set of coordinates, defined as follows: 
Let r be the position vector of a point with coordinates {x,y, z). We define the vertical altitude, Zy, 
of the point as the minimum distance between the point and the sea level surface. It is straightforward 
to demonstrate that 

{Re + Zyf = (Re + Zcf + (2.1) 
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where = + and Zc = z denotes the point's central altitude, an alternative way to express the 
z-coordinate which stresses the fact that this coordinate is always measured along the same central 
axis. The redundant set of coordinates 

{x,y,Zc,z„) {2.2) 

is used by AIRES to define the position of a point. The difference between Zc and z^, gives information 
about how far from the z-axis is the point, and in the "plane Earth" zone z^ is set equal to Zc- 

This way of taking into account the Earth's shape in the simulations proved to be accurate enough 
when compared with exact procedures while being economic from the computational point of view, 



as shown in section |L2| (page g). 



2.1.2 Atmosphere 

The Earth's atmosphere is the medium where the particles of the shower propagate and their evolution 
depends strongly on its characteristics. The simulations must therefore be based on realistic models 
of the relevant atmospheric quantities. 

The atmosphere has been extensively measured and studied during the last decades. As a result, 
a variety of models and parameterizations of measured data have been published. Among them, the 



so-called US standard atmosphere [ ]12| ] is a widely used model based on experimental dataQ. We have 
selected it as a convenient model to use in AIRES which gives an acceptably realistic approximation 
of the average atmosphere. 

An evident characteristic of the atmospheric medium is that of being inhomogeneous. Its density, 
for instance, diminishes six orders of magnitude when the altitude above sea level passes from zero 



to 100 km, and another additional six orders for the range 100 km to 300 km [13]. This fact is taken 
into account in the model we have selected, where most of the relevant observables are regarded as 
functions of the altitude above sea level, or vertical altitude, h: The atmosphere is thus a spherically 
symmetric "layer" a few hundreds kilometers thick, whose internal radius is the Earth's radius (6370 
km). 

For a variety of processes that the particles can undergo during the development of the shower, it 
is essential to know the chemical composition as well as the density of the medium they ai^e passing 



thi^ough [|14|]. For this reason, we have studied the behavior of these two quantities, especially their 
dependence with the vertical altitude. 

The chemical composition of the air, as given by the mean molecular weight, remains virtually 
unchanged in all the region < /i < 90 km, and diminishes progressively for larger values of h. 



This clearly shows up in figure |2.2| , where the US standard atmosphere mean molecular weight [ |13| ] 
has been plotted versus the vertical altitude. The constant value M = 28.966 is the mean molecular- 
weight corresponding to an atomic mixture of 78.47% N, 21.05% O, 0.47% Ar and 0.03% other 
elements. The corresponding mean atomic weight (atomic number) is 14.555 (7.265). The ratio 
between mean atomic number and weight is 0.499. 



'The US standard atmosphere is sometimes referred as the US extension of the ICAO (International Civil Aviation 
Organization) standard atmosphere. 
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Figure 2.2. Mean molecular 
weight of the atmosphere as a 
function of the vertical 
altitude (US standard 
atmosphere JT3|]). The Une is 
only to guide the eye. 



On the other hand, the density of the air does change considerably with the vertical altitude, as 



shown in figure 2.3. The dots are the US standard atmosphere data, taken from reference [13]. The 



green full line con^esponds to Linsley's parameterization of the US standard atmosphere [[1511, also 
called Linsley's atmospheric model or Linsley's model, which effectively reproduces very accurately 
the US standard atmosphere data. The isothermal atmosphere 

-gMh/RT 



p{h) = po e~ 



(2.3) 



was also plotted (dotted red line) for comparison. pQ and T match the corresponding US standard 
atmosphere values at sea level. 
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Figure 2.3. Density of the air 
as a function of the vertical 
altitude. The dots represent 
the US standard atmosphere 



data [13], while the full green 



line con^esponds to Linsley's 
model [ |T5[ ] and the dashed 
red one to the isothermal 
atmosphere 

p{h) = Po e-9Mh/RT ^iti^ 

Po = L225 kg/m\ 

M = 28.966 and T = 288 K. 



It is worthwhile mentioning that Linsley's model is limited to altitudes h < /imax with /imax = 
112.8 km. The density is considered to be zero for h > /imax- This approximation helps very much 
to simplify different algorithms used in air shower simulations while being absolutely justified since 
only affects an atmospheric zone placed much above the region where the air showers take place, 
which at most extends up to 50 vertical kilometers above sea level. 
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Figure 2.4. Vertical atmospheric depth, X^, versus vertical altitude over sea level, h, accordingly 



with Linsley's model [15]. 



For the same reason, the chemical composition of the air can be assumed to be constant in the 
full range of non- vanishing density {0 < h < /imax)- As shown in figure 2.2, this only affect the very 
upper layer of the atmosphere, with altitudes larger than 90 km. 

A further approximation that will be made when necessary is to assume that the air is a "pure" 
substance made with "air" atoms whose nuclei possess chai^ge Z^s and mass number A^a. To match 
the actual molecular weight, it is necessary to set Z^s = 7.3 and {Zcs/Acs) = 0.5 [|l|]. 

The density of the air is not directly used by the related algorithms: The quantity that naturally 
describes the varying density of the atmospheric medium is the so called vertical atmospheric depth, 
Xy, defined as follows: 

Xy{h) = / p{z) dz. (2.4) 



The integration path is the vertical line that goes from the given altitude, h, up to infinity. The usual 
unit to express X^ is g/cm^. In figures ^ and 2.5, Xy{h) (Linsley's model) is plotted against h. 
Notice that X„(0) ^ 1000 g/cm^ and Xy{h) ^ for ^ ^ oo as expected. 



Chapter 2. General characteristics of AIRES 



15 




p{h) can be obtained from via 

Linsley's parameterization of X^{h) [p3|], is done as follows: (i) The atmosphere is divided in 
L layers. For / = 1, . . . ,L layer I starts (ends) at altitude hi (/li+i). It is clear that hi = and 
hi+i = /imax- (ii) X^{h) is given by: 

ai + bie-'^/^' hi<h<hi+i, l = l,...,L-l 
X.o{h) = { ai- bUh/cL) hi < h < hL+i (2.6) 
h>hL+i. 

Where the coefficients ai, hi and q, Z = 1, . . . , L are adjusted to fit the corresponding experimental 
data. The coefficients used in AIRES^ which correspond to a model with L = 5 layers, are listed in 



table and are the ones that come out from a fit to the US standard atmosphere data. The Linsley's 



model prediction for p{h) plotted in figure g3| was obtained using this coefficient set and equations 
^ and dJ). 

Another important property of Linsley's parameterization is that Xy{h) can easily be inverted to 
obtain h = ^-^(X) {X > 0): Let Xi = X^{hi), l = l,...,L, then 





' -Q ln(^ 


H 




, CL{aL - 



X - ai 



Xi+i<X<Xi, l = l,...,L-l 

~ (2.7) 

0<X <Xl, 



^These coefficients correspond to the default setting, and are coincident with the ones used in the program MOCCA 
iQ]. In the current version of AIRES an alternative set of coefficients corresponding to a South Pole atmosphere is also 
available. 
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Layer 


Layer limits (km) 


ai 


hi 


Q 


I 


From 


To 


(g/cm^) 


(g/cm2) 


(m) 


1 





4 


-186.5562 


1222.6562 


9941.8638 


2 


4 


10 


-94.9199 


1 144.9069 


8781.5355 


3 


10 


40 


0.61289 


1305.5948 


6361.4304 


4 


40 


100 


0.0 


540.1778 


7721.7016 


5 


100 


~113 


0.01128292 


1 


10^ 



Table 2.1. Linsley's model coefficients for the US standard atmosphere []15|]. The number of layers 
is L = 5. 



where the replacement Xy{hL+i) = has been made. 

A quantity related to the vertical depth that appears frequently in air shower calculations is the 



slant atmospheric depth, Xs, defined similarly as (equation (2.4)) but using a non- vertical inte- 
gration path. In most applications the integration path is a straight line going along the shower axis, 
from the given point to infinity. In this case Xg takes the form: 



Xs{z) = J p{z„)dl, (2.8) 
where the prime in the integral indicates that the path is along a non- vertical line and is the vertical 



altitude defined in equation (2.1). 



The integral in equation ( [2.8| ) cannot be solved analytically in the general case of an arbitrary 
geometry (see page |189| ). If the Earth's curvature is not taken into account (plane Earth), then it is 
straightforward to prove that 

Xs{h) = (2.9) 
cos 9 

where B is the zenith angle of the shower axis (see section [2. 1.1[ ). From this equation it comes out 
that Xs depends not only on h but also on Q and the location of the ground surface. 

Unless otherwise specified, any reference to atmospheric depth, or depth, is assumed to be a 
reference to Xy which may also be noted simply X^ 

2.1.3 The slant depth and the Earth's curvature. 

Many air shower observables, especially the ground level distributions, depend on the thickness of 
the air layer that separates the starting point of an air shower from the ground level. For non-vertical 
showers starting at the top of the atmosphere, this thickness is measured in terms of the slant depth 



evaluated at ground level, Xs{zg). The plane Earth approximation given by equation ( p!9| ) is usually 
employed to evaluate that quantity. However, this approximate equation can give inaccurate estima- 
tions for large zenith angles, and in fact it is divergent for = 90°. 



^Notice that in some publications the symbol X is used to represent the slant depth. 
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Zenith angle 

(dee) 


Curved Earth 


Plane Earth 


length (km) 


path (g/cm?) 


length (km) 


path (g/cm^) 


A 
U 


110 


1036.1 


110 


1036.1 


30 


127 


1195.9 


127 


1196.4 


45 


154 


1463.6 


156 


1465.3 


60 


215 


2065.1 


220 


2072.2 


70 


303 


3003.7 


322 


3029.4 


80 


518 


5765.5 


633 


5966.7 


85 


757 


10571.7 


1262 


11887.9 


89 


1083 


25919.3 


6303 


59367.2 


90 


1189 


36479.9 


oo 


oo 



Table 2.2. Total shower axis length (m) and slant path (g/cm^) measured from the top of the 
atmosphere (1 10 km.a.s.l) down to sea level, tabulated versus the zenith angle. 



To precisely estimate Xs{zg) we have evaluated numerically the integral of equation (2^) for 
various representative cases. In table 2/2 the results corresponding to Zg = (ground level located 



at sea level) are tabulated for different zenith angles. The top of the atmosphere is located at an 
altitude of 110 km.a.s.l, and Linsley's parameterization is used in the calculations. The respective 
data corresponding to the plane Earth model are also tabulated for comparison purposes. 

The tabulated quantities indicate that the plane and curved Earth estimations differ in less than 
4% for all zenith angles B < 80°, and the differences increase notably as long as the zenith angle 
approaches 90°. 

The geometrical length of the shower axis, a, is also tabulated for both models. In the plane Earth 
approximation this length is given by 

a= — ^, (2.10) 

cos c) 

where Zmax is the (vertical) altitude of the top of the atmosphere (1 10 km in the present case). On the 
other hand, if the Earth's curvature is taken into account, the expression for a becomes 



{Re + 2t,max)2 " (^e + Zgf sill^ 6 - (i?e + Zg) COS 9, (2.11) 



where Zijmax stands for the vertical altitude of the injection point (110 km). Equation ( [2. 10| ) is the 



Re ^ oo limit of equation (2.11). 



2.1 .4 Range of validity of the "plane Earth" approximation 

In section [2.1. 1| (page [T^ it is specified that the limit of the "plane Earth" zone is located at a certain 
distance from the central z-axis. This distance varies Unearly with the altitude and goes from 4 km at 
sea level up to 22.5 km at 100 km above sea level. 
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To determine the boundaries of that zone, that is, a region where plane geometry can safely be 
used in the involved procedures, the requirement of expressing the vertical depth of a given point 
with enough precision was taken into account. The condition actually imposed can be defined in the 
following terms: Let d be the horizontal distance of a certain point to the z-axis, and let z and Zy be 
the point's central and vertical altitudes. Let 

AX{d) = Xy{z,)-Xy{z). (2.12) 

In a plane geometry, AX is zero for all d provided z is kept fixed. We can use this quantity to 
determine a safe "plane zone" imposing a bound on AX. After a series of technical considerations, 
too many to be explained in detail here, we concluded that the geometry can be acceptably taken as 
plane for all points whose distances to the z-axis are less than dmax defined by the condition[|: 

AX((imax) < 0.25 g/cm2 AND 2 AX(dmax) < 1% x X^{z). (2.13) 



Using equations (|j) and ( |2. 13| ), and taking into account that AX = {zy — z)p{z), it is simple to 
obtain estimations for dmax at different altitudes. At sea level, for example, where the vertical depth 
is approximately 1030 g/cm^, and the density of the air is 1.22 kg/m^, we obtain 

(imax < 5.5 km. (2.14) 

The same calculation for 100 km above sea level yields 

dmax<24km. (2.15) 



The boundaries of used by AIRES (see section 2.1.1) agree with these results. 



2.1.5 Geomagnetic field 

All charged particles that move near the Earth are deflected by the geomagnetic field. Such deflections 
are taken into account in the internal algorithms of AIRES. 

The Earth's magnetic field, B, is described by its strength, F, F = ||B||; its inclination, I, defined 
as the angle between the local horizontal plane and the field vector; and its declination, D, defined 
as the angle between the horizontal component of B, H, and the geographical North (direction of 
the local meridian). The angle I is positive when B points downwards and D is positive when H is 
inclined towards the East. 

Let {Bx, By,Bz) be the Cartesian components of B with respect to the AIRES coordinate system 
(section [2.1.1| ). They can be obtained from the field's strength and inclination via 

Bx = Fcosl, By = 0, B^ = -Fsml. (2.16) 

''This requirement is more stringent that the one used for AIRES version 1.4.2a or earlier The original equations [Q] 
were not adequate in certain particular conditions, namely, quasi-horizontal showers, and were thus modified. 
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By is always zero by construction, since in the AIRES coordinate system the x-axis points to the local 
magnetic north, defined as the direction of the H component of the geomagnetic field. 

There are two alternatives for specifying the geomagnetic field in AIRES : (i) Manually, entering 
F, I and D. (ii) Giving the geographical coordinates, altitude and date of a given event. In the later 
case, the magnetic field is evaluated using the International Geomagnetic Reference Field (IGRF) [Q], 
a widely used model based on experimental data that gives accurate estimations of all the components 
of the Earth's magnetic field. 

We are not going to place here any further analysis of the geomagnetic field and its implementation 
in an air shower simulation program. The interested reader can consult reference [ |T^ ] which contains 
a detailed description of general aspects of the geomagnetic field and the IGRF, together with a 
discussion about the practical implementation of the deflection procedure and an analysis of the effect 
of the geomagnetic field on several air shower observables. 



2.2 Air showers and particle pliysics 

We are going to describe here how the particles of an air shower are identified and processed and 
which interactions are taken into account. 



2.2.1 Particle codes. 

AIRES recognizes all the particles commonly taken into account in air shower simulations plus ad- 
ditional ones included for completeness. Each particle is internally identified by a particle code. It 
is important to notice, however, that user level particle specifications are made by means of particle 
names instead of numeric codes. 

Table lists AIRES particle codes, together with the corresponding particle names and syn- 
onyms. 

Nuclear codes are set taking into account Z (atomic number), (number of neutrons) and A = 
Z + N (mass number), in a computationally convenient codification formula: 

code = 100 + 32Z + (AT- Z + 8), (2.17) 

with 0<A^ — Z + 8<31. Taking 1 < Z < 26 (from hydrogen to iron), this coding system allows 
to uniquely identify all known isotopes. 

Regarding the names of nuclei, they can be specified in several ways: (i) By their chemical names, 
for example Fe'56 (56 refers to the mass number A, which defaults to the most abundant isotope's 
mass number when not specified), (ii) By special names, as Deuterium for or Iron for Fe^^. (iii) 
By direct specification of Z, N and/or A, for example NZ 2 2 (He^), ZA 26 54 (Fe^"^), etc. 

In certain cases it may be needed to refer to groups of particles having some properties in common. 
There are several particle groups defined in the AIRES system which can be useful in such situations. 



The most important groups of particles are listed in table 
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Particle 


Code 


Name and synonyms 
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Til 1 


Ve 


— O 


nubar(e) 
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nu(m) 




—7 


nubar(m) 








nu(t) 
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nubar(t) 
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piu 




1 1 
1 1 


pi+ 




1 1 

— 11 


pi- 




iZ 


IvUo 




13 


KUL 


K+ 


14 


K+ 


K- 


-14 


K- 


V 


15 


eta 


n 


30 


n Neutron neutron 


n 


-30 


nbar AntiNeutron antineutron 


P 


31 


p Proton proton 


P 


-31 


pbai- AntiProton antiproton 



Table 2.3. AIRES particle codes and names. The nucleai^ coding system and nucleai^ names are 
explained in the text. 

2.2.2 Interactions taken into account in the current version of AIRES 

The processes which ai^e most relevant from the probabilistic point of view are taken into account in 
AIRES. In the current version (2.2.0) the set of considered processes is similar to the corresponding 
one from the MOCCA simulation program and includes the following interactions: 

• Electrodynamical processes: 

- Pair production and e+e" annihilation. 

- Bremsstrahlung (electrons and positrons). 
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Group name and synonyms 


Particles in the group 


NoParticles None 


Empty group 


AllParticles All 


Universal group containing all particles 


AllCharged 


All charged particles, including all nuclei 


MassiveNeutral 


All non-charged massive particles 


Nuclei 


All nuclei 


Neutrinos 


All neutrinos and anti-neutrinos 


e+- 


_i_ 

e^, e 


muH — 




tauH — 




GPion 


tt"^, 7r~, vr^ 


GChPion 




GKaon 


K+, Kl Kl 


GChKaon 


K+, K- 


nppbar 


n, p, p 


nnbai- 


n, n 


Nucnucbr 


n, n, p, p 



Table 2.4. AIRES particle groups. 



- Emission of "knock-on" electrons (5 rays). 

- Compton and photoelectric effects. 

- LPM effect and dielectric suppression]^ 

• Hadronic processes: 

- Inelastic collisions hadron-nucleus. 

- Photonuclear reactions. 

- Nuclear fragmentation, elastic and inelastic. 

• Unstable particle decays. 

• Particle propagation: 

- Medium energy losses (ionization). 

- Coulomb and multiple scattering. 

^The algorithms corresponding to the LPM effect and dielectric suppression were completely rewritten for AIRES ver- 
sion 1.4.2, and emulate Migdal's theory |p^. The procedures included in previous versions of AIRES, namely 1.2.0 and 
1.4.0, are numerically incorrect leading to an "excessive" suppression effect which affects the results of the simulations in 
certain circumstances [p^]. This bug is present also in MOCCA's LPM procedures, as reported by D. Heck [p^]. Addition- 
ally, the previous algorithms do not take into account the effect of the dielectric suppression. 
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The hadronic inelastic collisions and photonuclear reactions are processed by means of exter- 
nal hadronic interaction models when their energy is above a certain threshold; otherwise they are 



calculated using Hillas' splitting algorithm m, 20] 



AIRES includes (optionally) links to two well-known external hadronic interaction packages, 
namely, SIBYLL if] and QGSJET 

2.2.3 Processing the interactions 

We are going to briefly describe how the different interactions are processed in AIRES. We shall focus 
in the computational aspects of these procedures; a more detailed description of the physics involved 



in such processes is going to be published elsewhere []21p. 

Most of the procedures here described are part of the group of physical algorithms already intro- 
duced, and virtually all of them are implemented equivalently as in the simulation program MOCCA 

i- 

First of all it is necessary to express that this description is a general one: The actual algorithms do 
include a number of technical details whose complete explanation is beyond the scope of this work, 
even if their philosophy is concordant with the scheme here presented. 

As mentioned below, in AIRES the particles are stored in arrays (stacks) and processed sequen- 
tially. Each particle entry consists of different data items containing the different variables that char- 
acterize it: Particle code, energy, position, direction of motion, etc. 

For the simulation engine, the shower starts when the primary particle is added to the previously 
empty stack. Then the stack processing loop begins. 

Let E, r, t, u be respectively the kinetic energy, position, time and direction of motion of a given 
particle identified by its particle code kp. When this particle is going to be processed it will suffer 
one of several possible interactions Ij, i = 1, . . . , n, n > 1. To fix ideas, let us consider the case of 
a positron. The possible interactions, /j, are: annihilation, interaction with an atom from the medium 
and emission of a "knock-on" electron, and emission of a bremsstrahlung photon. 

Evaluating the mean free paths 

Every interaction Ij is characterized by its cross section, ai, or, equivalently, by its mean free path, 
Aj. Aj and ai are connected via: 

A. = ^, (2.18) 

where rriair is the mass of an atom of the medium the particle propagates trough, that is, an average 
atom of "air" in the case of air showers. The usual units for Aj are g/cw?. 

The mean free paths do depend on the kind of interaction and on the particle's instantaneous pa- 
rameters. They can be calculated analytically for certain interactions; in other cases they must be 
estimated by means of par ameterization of experimental data, and this generally requires extrapola- 
tions out of the region corresponding to the measurements. A typical example of this situation is the 
case of the mean free paths for inelastic collisions particle-nucleus, where "particle" can be proton. 
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gamma, other nucleus, etc. Such mean free paths depend on the energy of the projectile particle, and 
must be calculated for energies well above the maximum energies attainable in collider experiments. 

Figure 2.6 contains plots of the mean free paths corresponding to proton-nucleus, pion-nucleus, 
kaon-nucleus and Fe-nucleus collisions, plotted as a function of the projectile energy. All the alterna- 
tive sets of mean free paths available in AIRES are displayed. 



Selecting the particle's fate 

For each interaction i, Aj represents the mean path (expressed in "quantity of matter", that is, g/cm^) 
the particle should move before actually suffering the interaction. To evaluate the actual path to a 
given interaction, it is necessary to sample the corresponding exponential probability distribution, 
Pi{Pi) = exp(— pi/Aj). Let pi, i = 1,... ,n the set of values obtained after sampling the 
corresponding distributions for all the possible interactions. 

The interaction the particle will actually undergo, also called the fate of the particle, is then 
selected: It is the interaction j corresponding to the minimum of the pfs, that is, pj < pi for all i. 



Moving the particle and processing the selected interaction 

After the particle's fate has been decided, the corresponding interaction begins to be processed. First, 
the particle must be advanced the path indicated by pj. It is necessary to convert the path in a geomet- 
rical distance, and this depends on the atmospheric model and the particle's current position. In the 
case of charged particles, the advancing procedure also takes care of the ionization energy losses, the 
scattering and the geomagnetic field deflection. During this step, the particle's coordinates, direction 
of motion and energy can be altered. 

The final step is to process the interaction itself. This generally involves the creation of new par- 
ticles (secondaries) which are added to the corresponding stacks and remain waiting to be processed, 
and eventually the deletion of the current particle, for example in the case of positron annihilation. 

In some cases, it is necessary to apply corrections to the probability distributions used to determine 
the particle's fate. This happens with processes which have rapidly changing cross sections, or by 
coiTcctive processes not taken into account in the original selection^. The result of the corrective 
action is that of canceling some interactions. In such cases the particle is left unchanged and remains 
in the stack for further processing. 



Particles arriving to destination 

The mechanism so far described is capable of generating and propagating all the secondaries that 
come after the first interaction of the primary particle. To let the shower finish it is necessary to 

"^The Landau-Pomeranchuk-Migdal (LPM) effect is an example of such kind of processes. The LPM effect 

implies a reduction of the cross section of , 7 processes at very high energies. In AIRES it is implemented as a corrective 
algorithm whose effect is that of rejecting a fraction of the previously "approved" processes. As a result, the correct cross 
sections are statistically preserved. 
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Figure 2.6. Hadronic mean free paths versus projectile energy (lab system). The solid (green), 
dashed (red), dotted (magenta) and dashed-dotted (blue) lines represent, respectively, the QGSJET, 
SIBYLL, Baitol, and Standard models. Notice that SIBYLL and Bartol plots are virtually identical. 
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determine when a particle should no more be tracked. In AIRES this corresponds to the case when 
one or more of the following conditions hold: 

• The particle's energy is below a given threshold (low energy particles)}]. 

• The particle's position is out of the interesting region (lost particles). 

• The particle reached the ground level. 

It is very simple to show that this is enough to ensure that the simulation of a shower will end in a 
finite time. 

Particle monitoring 

The simulation programs include several monitoring routines that constantly check the status of the 
particles being propagated and accumulate data then used to evaluate the different air shower observ- 
ables. 

The events that are monitored are: 

• Particles that reach ground level. 

• Particles that pass across predetermined observing levels. The observing levels are constant 
depth surfaces generally located between the injection and ground levels, and separated by a 
constant depth increment AX,,: If Ng is the number of observing levels (No > 1), and Xo^^ 
{Xo^°^) is the vertical depth of the first (last) observing level (xi^^ < Xo^°^), then the vertical 
depth of the other observing levels is given by 

AX, = ^° 

No -I (2.19) 
Xj,'^ = X(i) + l)AXo, i = l,...,No. 
Notice that the first observing level is that of highest altitude. 

• Charged particles that move across the air. For such particles the continuous energy losses by 
ionization of the medium are evaluated and recorded. 

The data collected by the monitoring routines are used to evaluate different kind of observables, 
for example: 

Longitudinal development of the shower. Tabular data giving the number and energy of particles 
crossing each defined observing levels. 

Shower Maximum. The data collected for the longitudinal development of all charged particles are 
used to estimate the shower maximum, Xjnax> that is, the vertical depth of the point where the 
number of charged particles reaches its maximum (see section [4.1. l| ). 
^Unstable particles are forced to decays. 
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Lateral distributions. Frequency distributions recording the number of particles reaching ground, 
as a function of their distance to the shower core. 

Energy distributions. Energy spectra of the different particles at ground level. 

Arrival time distributions. Mean ground level amval time of different particle kinds as a function 
of their distance to the shower core. 

All the output coming from the monitoring routines is saved in the form of data tables that can be 
easily retrieved by the user (see chapter ^). 

2.2.4 Random number generator 

AIRES contains many procedures that require using random numbers, the most important example 
being the propagating procedures that were described in the preceding paragraphs. Those numbers 
are adequately generated by means of a built-in pseudorandom number generator whose source 
code is included within the AIRES distribution. 

During the eai^ly steps of AIRES development, the random number generator was checked with 
a series of tests, including uniformity and correlation tests among others. In particular-, this pseudo- 
random number generator passed the very stringent "random walk" and "block" tests described in 



reference [24]. 



A more detailed description of the different routines associated with the generation of random 
numbers can be found in appendix ^ (page 133 ). 



2.3 Statistical sampling of particles: The thinning algorithm 

The number of particles that are produced in an air shower grows significantly when the energy of the 
primary increases. For ultra high energy primaries that number can be lai^ge enough to make it im- 
possible to propagate all the secondaries even if the most powerful computers currently available are 
used. The total number of particles in a shower initiated by a 10^'^ eV proton primary is approximately 
10^^, being almost impossible even to store the necessary data for such an amount of particles. 

The simulations are made possible thanks to a statistical sampling mechanism which allows to 
propagate only a small representative fraction of the total number of particles. Statistical weights are 
assigned to the sampled particles in order to compensate for the rejected ones. At the beginning of 
the simulation, the shower primary is assigned a weight 1 . 

At the moment of evaluating averages to obtain the physical observables, each particle entry is 
weighted with the con^esponding statistical weight. For example, the observables coming from the 



monitoring routines, listed in section 13, are evaluated taking into account those statistical weights. 
On the other hand, unweighted distributions are simultaneously calculated in the cases of longitudinal, 
lateral and energy distributions. They are useful to monitor the behavior of the sampling algorithm. 

The sampling algorithm used in AIRES is called thinning algorithm or simply thinning. It is an 
extension of the thinning algorithm originally introduced by A. M. Hillas [@, [I]], and was implemented 
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modularly as a procedure which is independent of the units which manage the physical interactions. 
The original Hillas algorithm and the AIRES extended thinning algorithm are described in the fol- 
lowing sections. 

2.3.1 Hillas thinning algorithm 

Let us consider the process 

A ^ Bi B2 . . . Bn, n>l (2.20) 

where a "primary" particle A generates a set of n secondaries Bi, . . . , Bn- Let Ea {Esi) be the 
energy of A {Bi), and let £^th be a fixed energy called thinning energy. 

Before incorporating the secondaries to the simulating processes, the energy Ea is compared with 
E'th, and then: 

• H Ea > Etii, every secondary is analyzed separately, and accepted with probability^ 

1 if EB,>Eth 



P^ = i Eb, (2.21) 



Eth 

• If Ea < Eth, that necessarily means that the "primary" comes from a previous thinning op- 
eration. In this case only one of the n secondaries is conserved. It is selected among all the 
secondaries with probability 

Pi = ^\ . {222) 

This means that once the thinning energy is reached, the number of particles is no more in- 
creased. 

In both cases the weight of the accepted secondary particles is equal to the weight of particle A 
multiplied by the inverse of Pi. 

The fact that the statistical weights are set with the inverse of the acceptance probabilities ensures 
an unbiased sampling, that is, all the averages evaluated using the weighted particles will not depend 
on the thinning energy, and will be identical to the "exact" ones obtained for £'th = 0. Only the 
fluctuations are affected by the thinning level: If E'th is close to the primary energy, then the thinning 
process begins early in the shower development, and a low number of samples is obtained, with 
relatively lai^ge and fluctuating weights. On the other hand, low thinning energies lead to larger 
samples with less statistical fluctuations. 

Processing large samples demands more computer time, so lowering the thinning level makes the 
simulation more expensive from the computational point of view. 



The procedure actually used in AIRES implements this step in a technically different way, but retrieving statistically 
equivalent results. 
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2.3.2 AIRES extended thinning algorithm 

The thinning algorithm of AIRES (2.2.0) includes an additional feature which has proved to be helpful 
to diminish statistical weight fluctuations in many cases. This extended algorithm was designed to 
ensure that all the statistical weights are never larger that a certain positive number Wr > 1, specified 
as an external parameter. 

The mechanics of the AIRES extended algorithm can be summarized as follows: Let wa be the 
weight of particle A, and Wy < Wr/2 be an additional (internal) positive number. Consider the 
number of secondaries in the process ( [2.20 ). 



• If n < 3 then 

- If Wa > Wy or WA Ea/ mm{EBi , • • • , Eb„) > Wr then all the secondaries Bi, . . . , Bn 
are kept. 

- Otherwise the standard Hillas algorithm is used. 

• If n > 3 then the standard Hillas algorithm is always used, but if the weight of the single 
selected secondary, wb, happens to be larger than Wr, then m copies of the secondary are kept 
for further propagation, each one with weight w'b = WB/m. The integer m is adjusted to 
ensure that Wy < w'^ < Wr- 

In the current version of AIRES Wy = Wr/8 and 

Wr = AoEti,Wf. (2.23) 

where Aq is a constant equal to 14 GeV~^ and Wf is an external parameter which can be controlled 
by the user and that will be refen^ed as the statistical weight factor. Therefore, the AIRES extended 
thinning algorithm depends just on two external parameters, namely, £^th and Wf. Notice also that 
Wr depends on the absolute thinning energy E^h- The constant Aq was adjusted so that vlo^th gives 
approximately the position of the maximum of the all particles weight distribution (see below). If 
Wf — > oo the extended algorithm reduces to the standard Hillas procedure. 

It is a simple exercise to show that this extended thinning algorithm is unbiased while ensuring 
(by construction) that all the particle weights be smaller than the externally specified maximum value 



Wr of equation (2.23) 



It is worthwhile mentioning that this procedure is not equal to the thinning algorithm of Kobal, 
Filipcic and Zavrtanik [||], even if both algorithms do use the concept of keeping bounded the statis- 
tical weights. 

2.3.3 How does the thinning affect the simulations? 

The effect of the standard thinning on different observables evaluated during the simulations can be 



seen in figures [2.7| - [2.9[ All these simulations were done using identical initial conditions: 10^^ eV 
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Figure 2.7. Effect of the thinning energy on the fluctuations of the number of charged particles 
crossing the different observing levels during the shower development. Ten 10^^ eV vertical proton 
showers were averaged to obtain the data for each thinning level. The plots labelled (a), (b), (c), (d), 
correspond to -Eth /-E'prim = 10"'^, lO""^, 10~^ and 10^^, respectively. 



proton showers with vertical incidence; and considering four different thinning energies, namely, 
Eth/Eprim = 10"^ 10"'^ 10"^ and lO^'^. In all cases the weight limiting mechanism was disabled. 

Figure 2/7 (page 29) corresponds to the longitudinal development of all the charged particles, that 
is the total number of charged particles crossing the different observing levels, as a function of the 
observing levels' vertical depth. 

The plots in this figure show clearly how the statistical fluctuations diminish systematically as 
long as the thinning energy is lowered. Compare the plot for 10""^ relative thinning with the smooth 
plots obtained for the cases 10"^ and/or 10^^. As mentioned, the CPU time required increases each 
time the thinning energy is lowered. It is interesting to mention that the simulations done at 10"^ 
thinning level required some 6300 times more CPU time than the ones done with 10~^ thinning level. 

Notice also that the mean positions of the points corresponding to any given depth do not present 
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Figure 2.8. Effect of the thinning energy on the fluctuations of the lateral distribution of electrons 



and positrons, in the same conditions as in figure 2.7 



any evident dependence with the thinning energy, as expected since the Hillas thinning algorithm is 
an unbiased statistical sampling technique. This observation applies also for the plots of figures 2^ 
(page BO) and O (page pi]). 



The degree of reduction of the fluctuation does depend on the observable considered. In figure ^ 
(page 30) the lateral distribution of ground electrons and positrons is displayed, again for different 
thinning levels. It is noticeable the degree of persistence of the noisy fluctuations, which are not 
completely eliminated even in the 10^^ relative thinning case. 

The lateral distribution of muons displayed in figure 2.9 (page 31) reflects another characteristic 
of the thinning algorithm. Even if the fluctuations are very large for 10^'^ relative thinning level, they 
reduce immediately when the thinning is lowered. Compare for example with the plots of figure ^ 
(page ^). To understand the behavior of these distributions it is necessary to recall that the muons 
are very penetrating particles, that is, they undergo a very reduced number of interactions before 
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Figure 2.9. Effect of the thinning energy on the fluctuations of the lateral distribution of muons, in 



the same conditions as in figure 2.7 



reaching ground. Therefore their statistical weights remain small since they are products of a few 
factors, and this fact is responsible for the low level of fluctuations produced. On the other hand, 
ground electrons and positrons most likely come out after a long chain of processes involving many 
predecessor particles, and in such circumstances very large statistical weights are unavoidable, and 



hence the high level of fluctuations observed in the e~^e~ distribution of figure (page [30| ). 

The AIRES extended thinning algorithm can be useful to reduce such kind of fluctuations. To 
illustrate this point let us consider the sample plots displayed in figure 2.10 (page B^). 



The outstanding characteristic of these plots is the fact that the density fluctuations diminish 
when the weight factor is lowered. In the particular- cases of Wj = 1 and Wj = 0.5 the fluctuations 
corresponding to the 10"^ relative thinning are of the order of the ones corresponding to the 10"^ 
(Hillas algorithm) case (yellow band) which were plotted in all cases for reference. 



Looking at the distributions of weights displayed in figure |2. 1 1| (page ^3|), it is possible to under 
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Figure 2.10. Effect of the AIRES extended thinning on the fluctuations of the lateral distribution of 
electrons and positrons. The plots coiTcspond to 10^^ eV proton showers simulated with 
£^th/^prim = 10~^, and different weight factors. The yellow bands ( ) con^espond to 
simulations performed in similar conditions, but using the Hillas algorithm at 10~^ relative level. 
The width of the bands correspond to the average value plus and minus one RMS error of the mean. 



stand the action of the weight limiting mechanism. The distributions labeled "nl" (blue lines) corre- 
spond to the Hillas algorithm case (no weight limits). Considering the the distributions of weights 
for gammas as a typical case, it is evident that there is a small fraction of particles having weights 
up to three orders of magnitude larger than the most probable ones. This rare cases are generally the 
cause of many inconvenients that arise when analysing the data. The plots for finite Wf show clearly 
that the distributions present a sharp end (corresponding to the value of Wr). In the case Wf = 1 
the gamma distribution ends approximately at the maximum of the "nl" case curve, as expected from 
equation (2.23), where the factor Aq is "tuned" to give Wr near the distribution's maximum when Wf 
is equal to I. 
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Figure 2.11. Effect of the AIRES extended thinning on the distribution of weights for different 



particles (gammas, electrons and positrons, and muons), in the same conditions as in figure 2. 10 
Particles aniving at ground at less than 40 m from the shower core were not included. 
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Figure 2.12. Processor time 
requirements for the AIRES 
extended thinning algorithm, 
plotted versus Wj for 
different relative thinning 
levels. All cases correspond 
to 10^^ eV proton showers. 
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The weight limiting factor does not alter significantly the muon weight distribution (see figure 



2.11). The reason for this is that muon weights are generally lower that the electromagnetic coun- 



terparts (see the discussion of figure in page ^0|), and therefore it is not likely that will reach 
the maximum externally imposed, which generally points to control the behavior of the electromag- 
netic particle entries. The key for elevating the quaUty of muon distributions is lowering the thinning 
energy. 

It is worthwhile mentioning that the weight distributions corresponding to other thinning energies 
have the same shape as the ones plotted in figure [2.1 1| (page but present a global shift in the 
abscissas scale which is proportional to the logarithm of the thinning level (for example, the weights 
for the 10~^ distribution are one order of magnitude lower than the ones for 10^^ and so on). 

The improvement in the lateral distribution plots is, of course, not free: The CPU time per shower 
is increased when Wj decreases. Figure 2.12 (page 33) represents the CPU time consumption per 
shower as a function of Wf for various thinning energies. The time unit is the average time required 
to complete a shower simulated with 10^^ relative thinning and Wj — > oo. 

The CPU time per shower increases monotonically when Wf decreases. For any Eth and Wj = 1, 
for example the required time is rougly 5 times larger than the one for Wj — > oo. But it is 1.6 (13) 
times lower than the one con^esponding to the Hillas algorithm for Eth/W (£'th/100). These figures 
may represent an important time saving factor in certain circumstances, for example when evaluating 
lateral distributions like the ones of figure 2.10 (page ^ ). 

The use of the AIRES extended thinning algorithm with finite Wf is always recommended, how- 
ever. Even in the least favourable cases, it is possible to get smoother distributions for every observ- 
able setting Wf not larger than 20 and thus eliminating the particle entries with unacceptably large 
weights. 



2.4 Some typical results obtained with AIRES 

The last section of this chapter is dedicated to present some illustrative results coming from air shower 
simulations made with AIRES using typical initial conditions. 

Let us consider first the longitudinal development of showers started at the top of the atmosphere. 
As mentioned in section [O] (page ^), the number of particles in a shower increases initially, then 
reaches a maximum, and finally the shower attenuates as far as an increasing number of secondaries 
are produced with energies too low for further particle generation. This characteristic behavior is 



illustrated in figure 2.13 which contains plots of the longitudinal development for all particles, gam- 
mas, electrons and positrons, muons, pions, and kaons. The data used in this figure corresponds to an 
average over 75 vertical 300 EeV proton showers. 



The plots of figure 2. 13 also show us that the gammas are the most numerous particles crossing the 
observing levels placed near the shower maximum. The electromagnetic shower (gammas, electrons 
and positrons) accounts nearly for all the particles in the shower. Notice that near the ground level 
the number of muons, the next most numerous particles, is nearly two orders of magnitude smaller 
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Figure 2.13. Longitudinal development of 3 x 10^*^ eV vertical proton showers. The error bars 
coiTespond to one RMS eiTor of the mean and are generally smaller that the symbols. The primary 
particles are injected at the top of the atmosphere, and the ground is located at 300 m.a.s.l. The 
longitudinal development is recorded in 75 different observing levels 13 g/cm^ apart. The average 
position of the shower maximum is Xmax = (906.6 ±5.1) g/cm^. 




X [g/cm" 

Figure 2.14. Energy longitudinal development of 3 x lO^'' eV vertical proton showers (the 



conditions of the simulations ai^e as described in figure [2.13| ) 
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than the number of electrons and positrons^ The number of ground pions and kaons are even smaller, 
but at high altitudes these particles represent an important fraction of all the particles of the shower; 
they can be even more numerous than the muons. This is consistent with the fact that the hadronic 
interactions (producing lots of secondary pions and kaons) take place at the early stages of the shower 
development. 

AIRES simulation engine also records the energy carried by the different particles that cross 
each observing level. These energy longitudinal development data are plotted in figure 2.14, and 
correspond to the same set of showers used for the previous figures. 

The "all particles" plot gives the total energy carried by the tracked particles crossing every ob- 
serving level. Since neutrinos are not tracked, their energy is not included. At high altitude the 
medium energy losses are not important, and therefore the total energy carried by the shower par- 
ticles remain constant. But the available energy begins to diminish as long as such losses increase; 
this event being correlated to the growth of the electromagnetic part of the shower. In the case being 
considered, the energy recovered at ground level is about 44% of the primary energy. This figure 
should be taken only as a qualitative measure of the recovered energy since it depends strongly on the 
initial conditions of the simulation, for example the inclination of the shower. 

The hadronic character of the shower at its beginning shows up clearly when considering the pions 
plot. At high altitude, the energy carried by the pions represent a large fraction of the total energy, 
then this energy reaches a maximum and diminishes monotonically as long as the shower develops. 
Notice also the behavior of the muon energy, which is negligible when the shower starts but grows 
constantly overpassing the pion energy fraction near the ground level. 

Another observables normally used to describe the air showers are the lateral distributions of 
ground particles, that is, the number of particles as a function of their distance to the shower axis. 
In figure 2.15 the lateral distribution of various particle kinds are plotted considering distances to the 
core ranging between 50 and 2000 meters. The results con^espond to a single shower simulated with 
10"^ relative thinning. This very low thinning level is responsible for the noticeable smoothness of 
the distributions, maintained even at large distances from the core. 

The basic characteristics of the air shower lateral distributions can be seen from this plot: The 
electromagnetic component, that is, gammas, electrons and positrons, is the most important in number 
and, at the same time, spreads widely around the core that is the point of maximum particle density. 
In the other extreme, the nucleonic component, represented in figure 2.15 by the proton and neutron 
lateral distributions concentrates in a relatively narrow zone around the shower axis. On the other 
hand, even if the muon density is always smaller than the electromagnetic counterpart, it diminishes 
more slowly with the distance to the core, so the muon/electromagnetic ratio, results an increasing 
quantity. 

The energy spectra of the particles reaching ground constitutes also an important observable to 
take into account in the analysis of air showers. In figure 2.16 such distributions are plotted for the 



'The examples here presented are just to illustrate some general aspects of the air showers. The corresponding data 
need not accurately reproduce actual experimental data. This observation applies especially to the number of ground 
muons which seems to be strongly dependent on the hadronic model used in the simulations. 
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Figure 2.15. Lateral 
distribution of different kinds 
of particles reaching ground. 
The data corresponds to a 
single 10^^ eV vertical proton 
shower simulated with 10^*^ 
relative thinning. 



same 10" relative thinning single shower mentioned in the preceding paragraphs. The outstanding 
fact related to these graphs is that the gamma and e~^e~ energy distribution have their maximums for 
much lower energies than the corresponding to the maxima of muons, pions and nucleons. Therefore, 
even if the electromagnetic component of the shower accounts for the principal fractions of particle 
number and energy (see figures 2.13 and 2.14), the individual particles are relatively less energetic 
when compai^ed with the average muons, pions and nucleons. 

Another relevant observable to study is the distribution in time of the different particles that aiTive 
at ground level. In figure 2.17| the mean amval delay time, {At), is plotted as a function of the lateral 
distance. The anival time delay for each particle is the difference between the absolute arrival time 
and a global time to defined as the time required by light to go from the injection point (the top of 
the atmosphere is this example) to the ground surface, travelling along the shower axis. In a vertical 
shower all the delays are positive. To obtain the average values plotted in figure 2.17 , all the times 
corresponding to particles reaching ground around a certain distance r to the shower core are added 
up and divided by the corresponding number of particles. 

Two well-known characteristics of the time distribution can clearly be seen from the plots of 
figure 2.17: (i) The mean time delays are larger than the ones corresponding to a spherical front with 
center at the first interaction point, (ii) In average, muons arrive first, then electrons and positrons and 
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finally gammas. 

Non vertical showers present particular characteristics that merit a separate analysys. In figure 
2.18 the lateral distribution of gammas, electrons are muons ai^e represented as 2D false color plots 
(left column) and contour curves plots (right column). Notice that the data corresponds to a single 30 
EeV inclined proton shower (zenith angle 60 degrees) simulated using the AIRES extended thinning 
algorithm with a 10~^ thinning level and Wf = 20 (in number of processed entries, this is roughly 
equivalent to a 6 x 10"^ relative level Hillas thinning algorithm). The outstanding characteristic of 
these plots if that the isondensity curves do not posses cylindic symmetry, and thus the calculation of 
lateral distributions must be done with special care when the showers are not vertical. 

Inclined showers can be also significantly affected by the effect of the Earth's magnetic field. In 
figure 2.19 the positive and negative muon distributions are displayed using 2D diagrams similar to 
those of figure 2.18. The artificially large field strength used for this example (70 ^T) helps to put 
into clear evidence the effect of the geomagnetic deflections: The total j-C^ ^~ distribution becomes 
broader -in the direction of the normal to the plane determined by the magnetic field and the shower 
axis- than its counterpart for the case of no magnetic field. This effect also remains evident when 
projecting the distributions onto the shower front plane. In the case of the lower plots of figure 2.19 
the projection algorithm takes into account the shower attenuation. A detailed description of that 
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Figure 2.17. Mean arrival 
time distributions for lO^*^'^ 
eV vertical proton showers. 



procedure is beyond the scope of this section and will be pubUshed elsewhere [p^]. 

Using a realistic magnetic field of strength 25 fiT, the deflections are less evident, but not negli- 
gible as illustrated in figure 2.20| . 

The comments here presented are not intended to be a complete analysis of the influence of the 
geomagnetic field on air shower observables. The reader interested in a more detailed study of this 
subject can look up in reference [16]. 
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Figure 2.18. Lateral distributions of muons, electrons and gammas, represented as 2D false color 
plots (left column) and contour curves plots (right column). The positive x-axis is directed towards 
the aiTival direction. The data corresponds to a single 3 x 10^^ eV proton shower with a zenith angle 
of 70 degrees. The environmental parameters correspond to the El Nihuil site located in Argentina 



(see table |3.2|), and the simulations were done with a 10 thinning level and Wj = 20. 
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Figure 2.19. Lateral distributions of positive and negative muons, represented as 2D false color 
plots. The upper graphs correspond to raw data recorded at the ground surface, while the lower ones 
are projections onto the shower front plane using a special algorithm that takes into account the 



shower attenuation [[25|]. In the upper graphs the positive x-axis is directed towards the anival 
direction. The arrows represent the projection of the magnetic field onto the shower front plane. The 
data corresponds to a single 3 x 10^^ eV proton shower with a zenith angle of 70 degrees. The 



environmental parameters correspond to the El Nihuil site located in Argentina (see table [3.2[ ), but 
using an artificially large (70 /xT) vertical magnetic field. The simulations were done with a 10~® 
thinning level and Wj = 20. 
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Figure 2.20. Lateral distributions of positive and negative muons, represented as 2D false color 
plots. The upper graphs correspond to raw data recorded at the ground surface, while the lower ones 
are projections onto the shower front plane using a special algorithm that takes into account the 



shower attenuation [[25|]. In the upper graphs the positive x-axis is directed towards the anival 
direction. The arrows in the upper (lower) graphs represent the projection of the magnetic field onto 
the ground plane (shower front plane). The data corresponds to a single 3 x 10^^ eV proton shower 
with a zenith angle of 60 degrees and random azimuth. The environmental parameters correspond to 
the El Nihuil site located in Argentina (see table ^^ ), and the simulations were done with a 10~^ 
thinning level and Wj = 20. 



Chapter 3 

Steering the simulations 



There are many parameters that must be specified before and during an air shower simulation job. 
The Input Directive Language (IDL) is a part of the AIRES system and consists in some 70 human- 
readable directives that permit an efficient control of the simulations in a comfortable environment. 

The most common IDL directives are described in this chapter, and many illustrative examples 
are discussed; a detailed description of the IDL language is placed in appendix ^ (page |108| ). It is 
recommended to properly install the software (see appendix 0) before proceeding with the following 
sections. 

3.1 Tasks, processes and runs 

The simulation of high energy air showers is a CPU intensive task which can demand days and even 
weeks of processor time to complete. The AIRES program was designed taking this fact into account: 
It includes an "auto-saving" mechanism to periodically save into an internal dump file (IDF) all rele- 
vant simulation data. In case of a system failure, for example, the simulation process can be restarted 
at the point of the last auto-saving operation, thus avoiding loosing all the previous simulation effort. 

The processing block that goes between two consecutive auto-save operations is called a run. 
With task we mean a specific simulation job, as defined by the input directives (for example, a task 
can be "simulate ten proton showers"); and with process we identify a system process, which starts 
when AIRES is invoked and ends when control is returned to the operating system. 

A task can be completed after one or more processes, and there can be one or more runs within a 
process. The limit case consists in having a task finished in a single run (no auto-save) completed in 
a single process (the program invoked just once). 

3.2 The Input Directive Language (IDL) 

Both the main simulation programs Aires and AiresQ, and the summary program AiresSry read their 
input directives from the standard input channel, and use a common language to receive the user's 
instructions. This language is called Input Directive Language (IDL). 
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The IDL directives are written using free format, with one directive per hne (there are no "contin- 
uation lines", but each hne can contain up to 176 characters). Special characters like tab characters, 
for example, are treated as blank characters]^ 

All directives are scanned until either an End directive or an end of file is found. Most directives 
can be placed in any order within the input stream. 

IDL directives can be classified as dynamic or static. Dynamic directives are processed every 
time the input data is scanned. Static ones can be set only at the beginning of a task: Any subsequent 
setting will not be taken into account. For instance, the maximum CPU time per run is controlled 
by a dynamic directive (it can be changed at the beginning of every process, and is a parameter that 
does not affect the results of the simulation); the ground altitude, instead, is an example of a static 
parameter that cannot be changed during the simulations. 

The IDL sentence begins with the directive name. IDL is a case sensitive language, and in general 
directive names mix capital and lowercase letters. The directives can be abbreviated. Consider for 
example the following directive name Primary Particle . You must specify the underlined part, and 
may or may not use the remaining chai'acters (Primary, PrimaryPart, PrimaryParticle refer to the 
same instruction). 

3.2.1 A first example 

There are four directives that should be always specified before starting a simulation task, namely, 
the ones that control the task nameQ, the statements that provide the primary particle type and energy 
specifications and the directive which sets the total number of showers to be simulated. 

Such a minimal set of specifications can be expressed in terms of IDL directives as follows: 

Task a_f irst_example 
Primary proton 
PrimaryEnergy 150 TeV 
TotalShowers 3 
End 

These directives, like most IDL directives, are self-explaining and posses a simple syntax. They 
can be placed in any order. Notice that the particles are specified by their names and physical quanti- 
ties like the energy, for example, are entered by means of a number plus a unit. 

3.2.2 Errors and input checl^ing 

Every IDL directive is checked for correct syntax when it is read in. Additionally, some elemental 
tests of the values given to the directive's parameters ai^e also made. When an eiTor is detected, 

'Special characters were not supported in AIRES 1.2.0. 

^Actually, the TaskName directive is not mandatory for a task to start, but its default value GIVE_ME Ji_NAME_PLEASE 
produces file names which are rather inconvenient to manage, and so it is strongly recommended to always set the name of 
a task before proceeding with the simulations. 
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a message is written to the standard output channel. Directives with errors are generally ignored. 
Consider the following directive: 

PrimaryEnergy 100 MeV 

If processed by AIRES, it will give the following error message 

EEEE 

EEEE Error message from commandparse 

EEEE Numeric parameter (s) invalid or out of range. 

EEEE >PrimaryEnergy 100 MeV< 

EEEE 

which indicates that the energy specification is out of rangej^ 

AIRES diagnostic messages always include a brief explanation about the circumstances that gen- 
erated the message, together with the name of the routine that originated it. The messages can be 
classified in four categories, accordingly with their severity: (i) Informative messages are used to 
notify the occurrence of certain events, and are generally associated with successfully concluded op- 
erations, (ii) Warning messages. Used to put in evidence certain not completely "normal" situations. 
In general, processing continues normally, (iii) Error messages indicate abnormal events like invalid 
input directives, etc., as illustrated in the previous example, (iv) Fatal messages are issued when a 
serious error takes place; in this case the program stops. 

The IDL instruction set includes some directives that allow checking a given input data set. Let 
us assume that the input directives are saved into a file named myfile.inp. Let us consider also that 
this file contains the instructions of the first example previously considered. 

The instruction set: 

Trace 

CheckOnly 

Input myfile.inp 

End 

if processed by AIRES will generate an output similar to the following: 

0:0002 CheckOnly 
0:0003 Input myfile.inp 
1:0001 Task a_f irst_example 
1:0002 Primary proton 
1:0003 PrimaryEnergy 150 TeV 
1:0004 TotalShowers 3 
1 : 0005 End 
0:0004 End 



^The primary energy must be greater than 10 GeV (see page 121 ). 
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The CheckOnly directive instructs AIRES to normally read and check the input data, and then stop 
without actually starting any simulations. The input lines placed after the Trace statement are echoed 
to the terminal, and the Input directives allows including IDL directives placed in other files. Notice 
the format used for directive echoing. It includes the line number as well as the file nesting level, 
starting by zero for the standard input channel. Input directives can be nested and permit splitting 
the input data into separate files. This is most useful for organizing a set of input files including some 
common directives in a single shared file included by every particular file, etc. 

In UNIX environments it is possible to use one of the scripts of the AIRES Runner System to 



automatically check a given input file. For details see chapter H (page 95 ) 



3.2.3 Obtaining online help 

The AIRES simulation and/or summary programs accept instructions that permit obtaining informa- 
tion about AIRES IDL instructions. The information that can be retrieved in this way is not extensive 
but it can be useful to the experienced user as a quick guide. 

Invoking AIRES interactively and typing "?" will return a list of the names of the IDL directives. 
"? *" will cause the list to include also the hidden directives. The prompt "Aires IDL>" typed at 
the terminal indicates that AIRES understands that this session is interactive. The Help command is 
similar to ? but it will maintain prompting disabled. 

There are two other kinds of help that can be obtained using the current AIRES version, namely, 
"? tables" and "? sites", which display the list of available output data tables (see section and/or 
appendix and the currently defined geographical sites (see section 3.3.4 ), respectively. 



The directive Exit, which can be abbreviated as x, will cause AIRES to stop immediately without 
any further action -not even completing the IDL instruction scanning phase- and is useful to end 
interactive help sessions. 

3.2.4 Physical units 

There are many IDL directives which include one or more specifications corresponding to physical 
quantities. In most cases these specifications have the format "number + unit", like in the Prima- 



ryEnergy specification of section 3.2. 1|, for instance. "Number" and "unit" are character strings, the 



first one indicates the decimal numerical value for the quantity being specified, while "unit" repre- 
sents the unit in which "number" is expressed. The characters used for the unit field resemble the 
name assigned in the real world to the corresponding unit, e.g. TeV for Tera-electron-volt. 

This feature of the IDL language makes the input files more readable, and diminishes drastically 
the possibility of enws in the specifications, especially for those quantities whose validity ranges may 
span many orders of magnitude. In such cases a number of commonly used multiples or sub-multiples 
of the fundamental unit are surely available. 



The complete list of units currently implemented is displayed in table 
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Magnitude 


Units 


Conversion factors 




Angle 


deq 
rad 


1 deg 
ISO/vrdeg 




Atmospheric depth 


cr/cm2 


1 g/cm^ 




Energy 


eV 
KeV 
MeV 
vse V 
TeV 

t C V 

EeV 
ZeV 


iU LreV 
10-6 GeV 
10-3 GeV 

1 VJC V 

10^ GeV 
10^ GeV 
10^ GeV 
10^2 QeV 
1 0^^ GpV 




i^eii^iii 


cm 


1 _„ 

lU 111 


lable 3.1. Physical units 




m 


1 m 


accepted within IDL 




KIM 


iU m 


directives. The underlined 


ividgneiic r leici 


nT 


1 nT 


keywords indicate the units 




uT 


1 n3 nT 

iu n i 


used internally to store the 




mT 

T 


1 n6 nT 

iU n i 
1 n'^ nT 


corresponding quantities. The 
magnetic field unit T (Gs) 




uG 


10-1 nT 


stands for the SI (cgs) unit 




mG 


10^ nT 


Tesla (Gauss), while gm 




Gs 


10^ nT 


corresponds to 7 (1 7 = 1 




gin 


1 nT 


nT). Time specifications using 


Time 


ns 


10-9 s 


hr, min and/or sec may 




sec 


1 s 


consist in the combination of 




min 


60s 


more that one field, like in 3 




hr 


3600 s 


hr 30 min, for example. 



3.2.5 Carrying on 



In figure 3.1a second example of an IDL input data set is displayed. Notice first that IDL instructions 
can be commented: All the characters following a '#' character are ignored. 

The Skip statement is also useful to place comments and/or introduce plain text in the input files 
(with no need of single line comment '#' characters), as well as to skip a part of the directives without 
deleting the lines. 

Comments and skipped lines are completely ignored: They just appear in the input file. Some- 
times this is not convenient, and it may be desirable to save their contents together with the output 
generated by the simulating program. The Remark directive provides a mean to do this. The state- 
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# 

# An example of an AIRES IDL input data set. 
Skip Snext 

The directive "Skip" skips all text until the label &label is 
found . Notice that it is not equivalent to a "go to" statement 
since it is not possible to skip backwards. 

As it can easily be seen, most directive names are self -explaining. 
&next 

Remark JUST AN EXAMPLE 

# The input directives define a "task". Tasks are identified by 

# their task name and (eventually) version. If not defined, the 

# version is zero. 

Task mytask # Use "Task mytask 5" to explicitly set task 
# version to 5 . 

# The following three directives are mandatory (have no default 

# values) 

TotalShowers 2 
PrimaryPart icle Proton 
PrimaryEnergy 1.5 PeV 

# 

# The remaining directives allow controlling many parameters of the 

# simulations. The respective parameters will take a default value 

# whenever the controlling directive is not present. 
# 

PrimaryZenAngle 15 deg 

Thinning l.e-4 Relative # Relative or absolute 

# specifications allowed. 

Ground 1000 g/cm2 

# You can freely set the number of observing levels to record the 

# shower longitudinal development. You can define up to 510 

# observing levels and (optionally) altitude of the highest and 

# lowest levels . 

ObservingLevels 41 100 g/cm2 900 g/cm2 



Figure 3.1. Sample AIRES input. 
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# 

# Threshold energies . Particles are not followed below these 

# energies. 



GammaCutEnergy 200 KeV 

ElectronCutEnergy 200 KeV 
MuonCutEnergy 1 MeV 

MesonCutEnergy 1.5 MeV # Pions, Kaons . 

NuclCutEnergy 150 MeV # Nucleons and nuclei. 



# 

# Some output control statements. 
# 



# Compressed particle data files related directives. 



SavelnFile Igtpcles e+ e- 

SaveNot InFile grdpcles gamma 



# Saving the ASCII (portable) version of the IDF file (ADF) , after 

# finishing the simulations. 



ADF On 



# No tables are printed or exported if no PrintTables ExportTables 

# directives are explicitly used. 
# 

# Longit . devel . of all charged particles. 

# Energy longitudinal development of muons . 

# Setting some options. 

# Here too. 



PrintTable 1291 
PrintTable 1707 
PrintTable 2207 Opt d 
PrintTable 3001 Opt M 
# 

ExportTable 2793 Opt M 
ExportTable 5501 



# Exported tables are placed in separate, 

# plain text files for further processing 

# (e . g . plotting) . 



End # End of input data stream. 



Figure 3.1 



( continued) 
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ment 

Remark JUST AN EXAMPLE 

placed in the example being discussed, instructs AIRES to place the comment 'JUST AN EXAMPLE' 
together with the output data. There is no limit in the number of remark instructions that may appear 
inside a given input instruction set. The Remark directive possesses another alternative syntax, very 
useful for multi-line text: 

Rem &eor 

This is the first line of a multi-line remark. 
This is the second line 

Spaces and TABS will be honored. 

The label &eor marks the end of the remark. 
&eor 

The input data set continues with the TaskName and the three mandatory directives already in- 



troduced in section 3.2.1 



The directives that follow set some characteristics of the showers that are going to be simulated. 



The PrimaryZenAngle directive gives the shower zenith angle, measured as indicated in figure 
(page |ll|). This directive, and the directive PrimaryAzimAngle permit the user to completely control 
the inclination of the shower axis. They can be used to set this incUnation to a fixed value, or to select 
variable settings selected at random with adequate probability distributions. In this case the alternative 



syntax of the directives should be used. For a more detailed description see section [3.3.3| (page [58| ) 
and/or appendix ^ (page 108 ). 



The GroundAltitude specification indicates the height above sea level of the ground surface 
(measured vertically). The specification can be a length or a vertical atmospheric depth expressed in 
g/cm^ (see page |116| ). On the other hand the statement 



ObservingLevels 41 100 g/cm2 90 g/cm2 



sets the variables No, Xh ' and Xr°' of equation ( |2.19| ). 

The IDL instructions continue with five directives that fix the cut energies for different particle 
kinds. Every particle whose kinetic energy falls below the threshold corresponding to its kind will be 



no more propagated by the simulation program, as explained in section 2.2. 3| (page 22). 



There are many observables that can be defined and studied to determine the behavior of air 
showers with given initial conditions. Generally only a small fraction of these observables are of 
interest for a determined user; and of course, the set of relevant observables do vary with the particular 
problem being studied. 

These somewhat contradictory facts were taken into account when designing AIRES output units, 
together with an analysis of the output system of existing programs |[T], As a result, the simulation 
program was provided with two air shower data output units: The particle data unit and the summary 
unit. 
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The particle data unit generates compressed particle data files containing detailed information 
(in a per particle basis) of particles reaching ground or passing across the different observing levels. 
The other output unit processes data stored in a number of internal tables (or histograms) which 
were calculated during the simulations and which correspond to standard observables like lateral 
distributions, energy distributions and so on. 

The output system will be treated in detail in chapter ^ (page Nevertheless, it is worthwhile 
mentioning here that there are several IDL directives that permit controlling its behavior. 



In our example of figure 3.1 (page 48), the directives SavelnFile and SaveNotlnFile control the 
kind of particles that are saved in the corresponding compressed files, identified by their extensions 
(Igtpcles and grdpcles). 

The default action for the file containing record for the particles reaching ground (extension grd- 
pcles) is that all particle kinds must be saved. On the other hand, no particles are saved by default in 
the longitudinal tracking particle file (extension Igtpcles). Therefore, the statements 

SavelnFile Igtpcles e+ e- 
SaveNotlnFile grdpcles gamma 

mean that only electrons and positrons are going to be saved in the longitudinal file, and that all 
particles but gamma rays are going to be recorded in the ground particle file. The particle kind 



specifications may include one or more particle or particle group names (see section 2.2.1). 

There may be more than one of these statements for each file, and their meaning depends on 
the order they are placed within the input data stream. As an example, let us consider the following 
statements: 

SavelnFile somefile None 
SavelnFile somefile Muons 

They ensure that only muon records will be saved in file^ somefile: The first statement "clears", and 
the second enables muons. If the order is changed: 

SavelnFile somefile Muons 
SavelnFile somefile None 

then the result is that somefile will be considered disabled because the last None specification prevents 
any particle kind from being saved in the corresponding file. 

The logical switch controlled by the instruction ADF On, enables the portable dump file, the 
portable version of the IDF file. 

The summary unit manages more than 180 output data tables that can be selectively included 
within the output data. Each table is identified by a numerical code, and the directives PrintTables 
and ExportTables permit including a table listing within one of the output files, or generating a 
separate plain text file with the corresponding table, respectively. The complete list of available 
tables is placed in appendix ^ (page |128| ). No tables are exported or "printed" if no Export or Print 
directives are included within the input data. Notice also that there are several options that modify the 
''somefile actually indicates the extension of the corresponding file, like grdpcles or Igtpcles for example. 
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resulting output. Such options control the normalization of histograms, output format, etc. A more 
detailed discussion on this subject is placed in section 4J_ (page [73| ). 

It is strongly recommended to edit a plain text file containing some IDL directives, run the simu- 
lation program and analyze the obtained output. In UNIX environments this can be made by means 
of the command 



Aires < myflle.inp 

or, alternatively^ 

AiresQ < myflle.inp 
myflle.inp is the name of the file containing the IDL directives. 



Input data listing 

The output typed at the terminal by any of the simulation programs will be similar to the sample 
displayed in figure Among other data, AIRES standard output includes a listing of the most 
important input parameters. All the parameters that are not explicitly set will take a default value. 
When default values are in effect, it is indicated with a (D) symbol placed before the parameter's 
description. All The variables included in this list can be modified by means of IDL instructions. 

The input parameter listing is divided in sections accordingly with the different kind of variables 
that control the computational and physical environment of the simulations. These sections are 

Run control. Includes aU the parameters controlling the conditions of the simulations, namely, the 
total number of showers, the number of showers per run, the number of runs per process and the 
(maximum) CPU time per run. The directives that control these variables are dynamic, and may 
therefore vary during the simulations. The quantities displayed in the input parameter listing 
correspond thus to instantaneous values of the mentioned parameters. 

File names. A listing with the names of all the files that will be created during the simulations (ex- 
cluding, of course, internal scratch files). A detailed description of the output files that can be 
created by the simulation programs, together with guidelines on how to manage them can be 
found in chapter ^ (page ^); we just give here a brief description of them: 

Log file {taskname. Igf). This file contains information about the events that took place during 
the simulations. It contains also a summary of the input parameters that were in effect. 
Most of the data that goes into the log file is also written into the standard output channel. 

^The program AiresQ uses the QGSJET hadronic model. The QGSJET initiahzation routines do employ a certain time 
to complete (up to half an hour in some systems), and therefore the execution time of the QGSJET simulations may be 
longer than the SIBYLL ones. Notice however that once the initializations are finished, all the relevant data is written 
into a special file. In the following invocations of the program such data will be read in from the file, thus reducing the 
initialization time. 
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>>>> 






>>>> 


This is AIRES version V.V.V (dd/Mmm/dddd) 




(Compiled by ... ) 






USER: xxxxx, HOST: xxxxx, DATE: 


dd/Mmm/yyyy 


>>>> 






> dd/Mmm/yyyy hh:min:ss. Reading data 


from standard input unit 


> dd/Mmm/yyyy hh;mm;ss. Displaying a 


summary of the input directives: 










REMARKS . 












JUST AN EXAMPLE 




>>>> 








PARAMETERS AND OPTIONS 


IN EFFECT. 








>>>> 


"(D)" indicates that the corresponding default value is being used. 


>>>> 








Task Name 


mytask 




RUN CONTROL: 






Total number of showers 


2 




(D) Showers per run 


Infinite 




(D) Runs per process 


Infinite 




(D) CPU time per run 


Infinite 




FILE NAMES: 






Log file 


mytask . Igf 




Binary dump file 


mytask . idf 




ASCII dump file 


mytask . adf 




Compressed data files 


mytask . grdpcles 






mytask . Igtpcles 




Table export file(s) 


mytask . tNNNN 




Output summary file 


mytask . sry 




BASIC PARAMETERS: 






(D) Site 


SiteOO 






(Lat: .00 deg. Long: .00 deg.) 




(D) Date 


dd/Mmm/yyyy 




Primary particle 


Proton 




Primary energy 


1.5000 PeV 




Primary zenith angle 


15.00 deg 




(D) Primary azimuth angle 


.00 deg 




(D) Zero azimuth direction 


Local magnetic north 




Thinning energy 


l.OOOOE-04 Relative 




(D) Injection altitude 


100.00 km (1.2829219E-03 g/cm2) 




Ground altitude 


297.96 m (1000.000 g/cm2) 




First obs. level altitude 


16.383 km (100.0000 g/cm2) 




Last obs. level altitude 


1.1733 km (900.0000 g/cm2) 




Obs . levels and depth step 


41 20.000 g/cm2 



Figure 3.2. Sample AIRES terminal output. 
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(D) Geomagnetic field: 

(D) Table energy limits: 

(D) Table radial limits: 

(D) Output file radial limits: 
(D) 



Off 

10.000 MeV to 1.1250 PeV 
50.000m to 2.0000 km 
100.00 m to 12.000 km (grdpcles) 
100.00 m to 12.000 km (Igtpcles) 



ADDITIONAL PARAMETERS: 



(D) 


Individual shower data: 


Brief 






Cut energy for gammas : 


200.00 


KeV 




Cut energy for e+ e- : 


200.00 


KeV 




Cut energy for mu+ mu- : 


1 .0000 


MeV 




Cut energy for mesons : 


1 . 5000 


MeV 




Cut energy for nucleons : 


150 .00 


MeV 


(D) 


Bartol inelastic mfp's: 


On 




(D) 


Gamma rough egy . cut : 


2 .0000 


MeV 


(D) 


e+e- rough egy. cut: 


2 .0000 


MeV 


(D) 


Hadronic Mean Free Paths : 


SIBYLL 




(D) 


SIBYLL switch: 


On 





MISCELLANEOUS : 

(D) Seed of random generator: 

(D) Atmospheric model: 



Automatic 

Linsley'' s standard atmosphere 



>>>> 

> dd/Mmm/yyyy hh:mm:ss. Beginning new task. 

> dd/Mmm/yyyy hh:mm:ss. Initializing SIBYLL 1.6 package. 

Initialization of the SIBYLL event generator 



(eventual output from SIBYLL) 



> dd/Mmm/yyyy hh:mm:ss. Initialization complete. 

> dd/Mmm/yyyy hh:mm:ss. Starting simulation of first shower. 

> dd/Mmm/yyyy hh:mm:ss. End of run number 1. 
CPU time for this run: .... 

> dd/Mmm/yyyy hh:mm:ss. Writing ASCII dump file. 

> dd/Mmm/yyyy hh:mm:ss. Task completed. 
Total number of showers: 2 

> dd/Mmm/yyyy hh:mm:ss. Writing summary file. 

> dd/Mmm/yyyy hh:mm:ss. End of processing. 



Figure 3.2 



(continued) 
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Summary file (taskname. sry, also taskname.tex). Output summary. This includes general 
simulation data and all the tables that were printed using IDL directive PrintTables. 

Exported data files (taskname. tnnnn). Plain text files containing output tables. 

Binary dump file (taskname. idf). This file contains (in machine-dependent binary format) all 
the relevant simulation data. This file is periodically updated during the task processing. 
In the case of an interruption, it is possible to restart the simulations from the last update. 
The file is also useful to obtain relevant data after the simulation is completed, or even 
during it. This can be done with the help of the summary program AiresSry. 

ASCII dump file (taskname. Portable version of the IDF file, written at the end of the 
task. Like the IDF file, this file can be processed with the summary program AiresSry. 

Compressed output files (taskname. grdipcXts and/or taskname. These files contain 
detailed particle data. The ground particle file, for example, consists of a series of records 
of all the particles that reached ground in specified circumstances. Thanks to the com- 
pressed data formatting used, it is possible to save a large number of particle records 
using a moderate amount of disk space. The format is universal, so the files can be writ- 
ten by a given machine and processed in a different one. The AIRES system includes a 
library of subroutines to process such files (see section |4.2[ ). 

Basic parameters. A list of geometrical and physical shower parameters. These variables define the 
initial conditions of the shower simulations (primary particle, axis inclination, etc.), as well 
as the settings that are in effect for the parameters of the monitoring algorithms (number of 
observing levels, range of radial distances for output files, etc.). 

Additional parameters. Other shower parameters, generally depending on the model used. Since 
the interactions models are replaceable, the type and number of additional parameters may 
vary when changing simulation programs. The variables included in this section as well as the 
directives that allow controlling them may also be changed in future versions of AIRES. By 
default, only the most relevant parameters^ are listed: Quantities associated with hidden IDL 
directives (see appendix ^) are not included. Nevertheless, AIRES can be instructed to produce 
a full listing, by means of the directive: InputListing Full. 

Miscellaneous parameters. Other parameters not included in the preceding sections. 



3.3 More on IDL directives 
3.3.1 Run control 



In the example of section 3.2.5 (page 47), no specifications are made about the duration of processes 
and runs. This fact shows up in the variables listed in the run control section of the listing of figure 3.2 



This also includes all the variables that were explicitly set by means of the corresponding IDL instructions. 
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(page q3|), when the default setting, "Infinite" is in effect for the number of showers per run, the num- 
ber of runs per process and the CPU time per run. With such settings, the auto-save mechanism for 
fault tolerant processing is disabled: The IDF file will be saved only after finishing all the simulations 
specified with the input directives. 

This can be acceptable for a short simulation in a reliable computer system. For heavy tasks it is 
recommended to split the simulations into processes and runs. It is worthwhile mentioning that the 
auto-save/restore operations do not alter the results of the simulations, which are bitwise identical 
independently of the number of such operations performed. 

The IDL directives ShowersPerRun, MaxCpuTimePerRun and RunsPerProcess provide ef- 
fective control on the computational conditions of the simulations. The following examples illustrate 
how them can be used. 

RunsPerProcess 1 
MaxCpuTimePerRun 2 hr 

These two instructions indicate that a new run should begin every two CPU hours. Since the number 
of runs per process is 1, a new run will also imply the beginning of a new process; in other words, 
the input file will be scanned every two CPU hours, allowing for eventual changes in the dynamical 
parameters of the simulations. 

RunsPerProcess 4 
ShowersPerRun 5 

Here the maximum CPU time is not set, indicating that there will be no time limit for a run to com- 
plete. Instead, every run will finish after concluding the simulations of five showers. The processes 
will end when four runs are completed. 

The three directives can also be used simultaneously: 

RunsPerProcess 2 
ShowersPerRun 2 
MaxCpuTimePerRun 6 hr 

These instructions indicate that a run will finish after six processing hours or after completing two 
showers, what happens first. 

The run control directives -like any other dynamic directive- can be modified during the simu- 
lations if needed. The changes will be effective after a new process is started (see section ^?T| ). Let 
us assume that a certain task is started with the control parameters of the previous example. After a 
while it is decided that the maximum cpu time per run is too high and that there is no need to limit 
the number of showers per run. The input file is thus modified: (i) The MaxCpuTimePerRun line is 
replaced by 

MaxCpuTimePerRun 3 hr 



(ii) The ShowersPerRun line is deleted. After finishing the current process (with the old settings this 
may demand up to 12 CPU hours) the input file is scanned again and the new settings will become 
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effective. The changes experimented by these dynamic parameters will be recorded in the log file 
(extension .Igf) in the following way 

> dd/Mmm/yyyy hh:mm:ss 

> dd/Mmm/yyyy hh:mm:ss 
From: 2 to: Infinite 

> dd/Mmm/yyyy hh:mm:ss 
From: 6 hr to: 3 hr 

The dynamic directives can be changed as many times as needed, including the total number of 
showers (controlled by directive TotalShowers) which can be modified either during the simulations 
or after completing them to append new showers to an already finished task|^ 

3.3.2 File directories used by AIRES 

The simulation programs read and/or write several files that contain different kinds of data. By default, 
all the files generated by AIRES are located in the working directory, defined as the current directory 
at the moment of invoking AIRES. 

There are certain cases, however, where this setting is not adequate. For that reason, the IDL 
instruction set contains directives allowing to control the placement of AIRES files. 

Let us first define the set of directories used by the AIRES system during the simulations: 

Global. Containing the log, IDF, ADF and summary files. 

Compressed output. Sometimes referred simply as Output directory, contains the compressed out- 
put files. 

Export. Containing all the exported data files. 

Scratch. Containing most of the internal files that are generated during the simulations, including 
the particle stack scratch files. 

The output and scratch directories default to the current working directory when not specified. On the 
other hand, the global and export directory default to the cuiTcnt setting of the output directory. 

The IDL directive FileDirectory permits complete control on the listed directories^ For example, 
the sequence of instructions: 

FileDirectory Scratch /mytmpdir 
FileDirectory Export /myexportdir 

'Notice however that it is not possible to append new showers to any taslc that was initialized with a previous version of 
AIRES. 

*The old syntax of version 1.4.2 is no longer supported. 



. Reading data from standard input unit 

. Changing maximum number of showers per run. 

. Changing maximum cpu time per run. 
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sets the scratch (export) to the strings (must be meaningful to the operating system) /mytmpdir 
(/myexportdir). The directory spacifications may be either absolute or relative. Relative speci- 
fications are always with respect to the working directory. In the preceding example the remaining 
directories are not specified, and will therefore take their respective default settings. 
The directive 

FileDirectory All /mydir 

simultaneously sets the global, output and export directories. 

There is an additional set of directories that can be specified while scanning the input data. The 
following instructions, for instance, 

InputPath /dirl:/dir2 
InputPath Append /dir3 

Input myinputf ile . inp 

will cause AIRES to search for file myinputfile.inp in all the three directories specified by means of 
the InputPath directives (notice the two alternative syntaxes) and -if not found there- in the current 
working directory. 

3.3.3 Defining the initial conditions 

There are two mandatory specifications related to shower parameters that must always appear within 
the input data, namely, primary particle kind and energy. 

These two specifications, together with other related ones permit a very wide range of specifica- 
tions for the shower parameters. Let us investigate some of the possible alternatives. 

Mixed composition 

The primary particle needs not be unique. AIRES allows for simulating showers with different pri- 
mary particles each. The following example illustrates this feature: 

PrimaryParticle Proton . 6 
PrimaryParticle Iron 0.4 

With such settings, the primary will be proton (iron) with 60% (40%) probability. This means that in 
100 simulated showers, approximately 60 will be proton showers while the remaining ones will have 
iron primaries. 

If n alternative primary particles, Pi, i = I, . . . ,n were defined, with weights Wi (wi ^ 0), then 
the probabiUty for any shower of being initiated by particle pj, I < j < nis given by 

Therefore, the weights entered in the IDL directives need not be normahzed. 

Besides this mixed composition feature, AIRES allows also to define special primary particles 



processed by external modules. For details see section |3^ (page |66[ ). 
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Varying energy 

The directive 



PrimaryEnergy E'min £^max 7 



(see page 121), indicates that the primary energies will be in the interval [-Emin, -Emax], selected with 



probability [20]: 

p{E) dE = U'^ ^-(T+i) dE, E^^ <E< Em.., (3.2) 

where 

U 



/ ^-(7+1) dE = I (3.3) 

[ In (S^ax/^min) 7 = 

7 can take any value. If not specified it is taken as 1.7. 
Zenith and azimutli angles 



The zenith angle directive placed in the example of figure 3. 1 (page Wq) corresponds to setting the an- 



gle to a fixed value. In this case the azimuth angle defaults to zero. On the other hand, the instruction 

PrimaryZenAngle deg 7 2 deg S 

indicates that the zenith angle distributes from 0° to 72° with sine distribution^ 

Psinc(e) dQ = sin e dG, G,nin < e < e^^x, (3.4) 

where 



-'max 



U = sin Q dQ = cos 0min — COS Gmax- (3.5) 

An alternative to the S specification is the SC (or CS) specification which corresponds to a sine- 
cosine distribution: 

^'sincos(e) dQ = sin e cos e dQ, e^in < e < e^ax, (3.6) 

where 



1 /-Wmax 1 

U = - sin(2e) dQ = - [cos(2e„,in) - cos(2Gmax)] • (3.7) 

2 Je 4 



1 |-6max , „ , „ 1 

For varying zenith angles, the default for the azimuth angle is to uniformly distribute in the interval 
[0°, 360°]. In this case the sine distribution con^esponds to showers with directions having a uniform 
solid angle distribution. 



'The sine distribution is sometimes called cosine distribution, relating it with the accumulative probability function of 



the sine distribution: Fsinc(6) = Psinc{u) du. 
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The azimuth angle can also be set as a varying angle. The directive 
PrimaryAzimAngle 37.2 deg 39.5 deg 

indicates that the azimuth $ will be uniformly distributed in the interval [37.2°, 39.5°]. 

Using simultaneously instructions for both the zenith and azimuth angles, it is possible to simulate 
showers coming from a determined direction in the celestial sphere. 

As pointed out in section |2. 1 . 1| (page 10), the x-axis (zero azimuth axis) corresponds to the local 



magnetic north. If desired, it is possible to specify geographic azimuths: 

PrimaryAzimAngle 3 7.2 deg 3 9.5 deg Geographic 

In the preceding directive, the Geographic keyword indicates that the origin of the azimuth angles is 
the direction of the local geographic north. It is worthwhile mentioning that this does not alter the 
axis definitions of section [2.1. 1| ; when geographic azimuths are in effect, the azimuth with respect to 
the AIRES coordinate system, ^, is evaluated via 

$ = D - ^-geographic (3.8) 



where D is the geomagnetic declination angle defined in section [2. 1.5| (page |18|). Notice that positive 



geographic azimuths indicate eastwards directions. For a complete description of this directive see 



page 121 



Position of injection, ground and observing ieveis 

The directives InjectionAltitude (or its synonym InjectionDepth), GroundAltitude (or its syn- 
onym GroundDepth) and ObservingLevels permit controlling the position of the injection point, 
the ground surface and the different observing levels, respectively. 



All the altitude specifications refer to vertical altitudes, noted as in figure 2. 1 (page 11), and can 
be expressed either as lengths (above sea level) or vertical atmospheric depths. Whenever necessary, 
AIRES transforms lengths into vertical depths and vice-versa using the current atmospheric model. 

Notice that the vertical altitudes are equal to the corresponding z-coordinates only for points 
located in the z-axis. To illustrate this point, let us consider the following instructions 

InjectionAltitude 10 km 
GroundAltitude 10 00 m 
PrimaryZenAngle 6 deg 

With such specifications, the primary particles will be injected at an altitude of 100 km above sea 
level, measured along the vertical passing by the injection point. Taking into account that the shower 



axis has an inclination of 60 degrees, and applying equation (2.1), it is possible to calculate the z- 
coordinate of the injection point, also referred as central injection altitude. In this case the result is 
Zc = 17962 m. 

The positions of the observing levels defined in section ^ (page 25) can be set using Observin- 
gLevels. This directive has two different formats: 
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(i) ObservingLevels No, with No an integer not less than 4. 

In this case the positions of the observing levels are set taking into account the injection and 
ground vertical depths. Let Xi (Xg) be the injection (ground) depth, then the spacing between 
observables and the positions of the first and last observing levels are set via 



Xo ^ — Xi + 
Xi^"^ = Xg- AXo 

(ii) ObservingLevels No Xa X^, with No an integer not less than 4 and Xa and X}, valid vertical 
depth or altitude specifications {Xa 7^ X},). 

In this second case the positions of the first and last observing levels are set accordingly with 
Xa and Xf,, with no dependence on the positions of the injection and ground levels: 

= min(X„, Xb), = max(X,, X^). (3.10) 



No + 1 

(3.9) 



The spacing between consecutive levels is evaluated using equation 2.19. 



3.3.4 Geomagnetic field 

The components of the Earth's magnetic field used by the simulation programs can either be set 



manually or calculated with the help of the IGRF model (see section [2. 1.5[ ). With the help of this 
model it is possible to obtain an accurate estimation of the geomagnetic field in a given geographic 
location and for a determined date. 

To activate this mechanism for "automatic" evaluation of the magnetic field, it is necessary to 
specify both a geographic place and a date. 

The directive Site tells AIRES the name of the site selected for the simulations. For example, 

Site SouthPole 

indicates that the selected place is "SoutiiPole". This name is one of the predefined locations that 
form the AIRES site library. Besides "SouthPole", this library initially contains several other sites 



related with air shower experiments. All the predefined sites are listed in table 3.2. 

To specify a site that is not included among the predefined ones, it is first necessary to append 
it to the site library by means of the AddSite directive. Let us consider, for instance, the following 
diixctive: 

AddSite eld -31.5 deg -64.2 deg 387 m 

A new site "eld" is defined. The command parameters represent, respectively, the latitude, longitude 
and altitude above sea level that correspond to the defined site. The name string cannot contain more 
than 16 characters; names are case sensitive and must be different to all the previously defined ones. 
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Sit€ name 


Latitude 


Longitude 


Altitude (m.a.s.l) 


SiteOO 


0.00° 


0.00° 





SouthPole 


90.00° S 


0.00° 


3127 


ElNihuil 


35.20° S 


69.20° W 


1400 


Millard 


39.10 N 


112.60 W 


1400 


AGASA 


35.78° N 


138.50° E 


900 


CASKADE 


49.09° N 


8.88° E 


112 


Dugway 


40.00° N 


113.00° W 


1550 


ElBarreal 


31.50° N 


107.00° W 


1200 


FlysEye 


41.00° N 


112.00° W 


850 


HaverahPark 


53.97° N 


1.64° W 


220 


Puebla 


19.50° N 


98.00° W 


2200 


Sydney An^ay 


30.50° S 


149.60° W 


250 


Yakutsk 


61.70° N 


129.40° E 


850 



Table 3.2. Predefined sites of the AIRES site library. Site names are case sensitive. The data for 



Haverah Park, Sydney Array and Yakutsk sites come from reference [26]. 



The Date directive defines the date of an event. There are two alternative syntaxes, as displayed 
in the following examples: 

Date 19 98.2 
Date 19 98 3 1 

In the first statement the date is given as a floating point number taking the year as the time unit, while 
in the second the format "year month day" is used. 

There are no special restrictions on the date specification. However, the IGRF database imple- 
mented in the current AIRES version contains data for the years 1955 to 1995. For dates outside 
that interval it is necessary to extrapolate the corresponding data in order to evaluate the geomagnetic 
field. This may lead to inaccurate estimations for dates very far from the validity range of the model 
(more than ten years away). Nevertheless, extrapolations near the given boundaries are acceptable, 
and are of course necessary for calculations beyond the yeai^ 1995 .[^ 

In case of missing date specification, it is set accordingly with the system time at the moment of 
starting the simulations. 

Once a site and a date are set, the Earth's magnetic field will be calculated by means of the IGRF 
model, unless it is explicitly set by means of the GeomagneticField directive. Let us analyze some 
examples (see also page |1 15|): 



GeomagneticField Off 

With this instruction the effect of the magnetic field on the motion of the charged particles will not 
be taken into account. However, the field will still be evaluated in order to determine the declination 



'"The next generation of IGRF data will be released after the year 2000. 
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angle, which is used to transform geographical azimuths into magnetic ones (see page pQ ). 

GeomagneticField 32 uT -60 deg 2 deg 
The preceding directive instructs AIRES to fully ovenide the IGRF estimation with the values in- 



dicated in the parameters, which respectively con^espond to F, I and D (see section 2.1.5). Partial 
overriding is also supported, like in the following instruction 

GeomagneticField 32 uT 

The field strength, F, will be set to the value indicated in the first parameter, while I and D will remain 
as given by the IGRF model. 

xz-plane Gaussian fluctuations, either absolute or relative, are also supported: 

GeomagneticField 32 uT Fluctuation 500 nT 
GeomagneticField On Fluctuation 10 % 

Notice that fluctuations can be introduced with or without overriding the IGRF field components. It 
is also possible to specify 0.1 Relative instead of 10 %. 

When magnetic fluctuations are in effect, then the magnetic field used for each shower will be 
different. Let Bq be the "central" value coming from the IGRF model and/or entered manually. Let 
AB be the specified fluctuations. Notice that in the case of relative fluctuations, AB is set using the 
field strength Bq: AB = BqABj-ci. 

Then for each new shower, two independent, Gaussian-distributed random numbers, ABx and 
ABz, having mean zero and standard deviation Ai?/\/2, are generated; and the magnetic field com- 
ponents are set via 

Bx = Bqx + ASa;, ^ 
Bz = Bqz + ABz- 

Notice, however, that the declination angle used for azimuth transformations will always come from 
the central value, that is, is not affected by the fluctuations introduced. 

3.3.5 Statistical sampling control 



The thinning algorithm described in section 2.3 (page 26) makes use of several external parameters 



that can be set by means of IDL directives. The thinning energy E^h is the most important param- 



eter of the thinning algorithm. As illustrated in figure 3.1 (page 48), the directive ThinningEnergy 
permits setting i^th> either absolutely or relative to the primary energy. 

The directive ThinningWFactor allows controlling the maximum weight parameter Wmax de- 



fined in section 2.3 (page 26). The specification 



ThinningWFactor 2 . 5 



sets the weight factor, Wf, of equation ( |2.23| ) to 2.5. 
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Recommended values for Wf are in the range 1 to 50. Setting Wf < 1 might noticeably increase 
the processor time requirements, and Wf > 100 is practically equivalent to Wj oo (see section 



3.3.6 Output table parameters 



The output tables listed in appendix ^ (page 128) are automatically calculated during the simulations, 



and the directives to retrieve these data will be explained in chapter ^ (page 73). Many of these tables 
can be customized by means of IDL instructions. 

The number of observing levels defined for the longitudinal tables (table numbers 1000 to 1999) 



can be controlled using the IDL directive ObservingLevels, as already explained in section p. 2.5 



(page 47). 



The lateral distribution tables (table numbers 2000 to 2499), the energy distribution tables (table 
numbers 2500 to 2999), and the mean amval time distribution tables (table numbers 3000 to 3499) 
are defined, by default, as histograms with 40 logarithmic bins (either radial or energy bins depending 
on the distribution type), plus two additional "underflow" and "overflow" bins. 

The IDL directives RLimsTables and ELimsTables allow to conti"ol the radial and energy bins, 
respectively, as illustrated in the following examples: 

RLimsTables 2 m 2 km 
ELimsTables 2 MeV 1 TeV 

The first directive sets the range for the standard lateral distributions. The lowest end of bin 1 (highest 
end of bin 40) is set to 20 m (2 km). The "underflow" bin will thus correspond to all entries with 
distances less than 20 m, while the "overflow" one to all entries beyond 2 km. 

In a completely similar way, the second directive sets the lower and upper bounds for the 40 bin 
energy distributions, and the respective "underflow" and "overflow" bins. 

With the current version of AIRES it is possible to save the tables in a shower per shower basis, 
besides the traditional average tables that have been always available. Since this may generate large 
IDF or ADF files in certain cases, the mechanism of individual shower table saving is disabled by 
default. The directive 

PerShowerData Full 

must be used to ensure that the individual shower tables are being saved. 



3.4 Input parameters for the interaction models 

The expression interaction models identifies a series of subroutines and functions that contain the 
actual implementations of the algorithms that control the propagation of particles. Such algorithms 
emulate the physical rules associated with the different interactions that take place in an air shower. 

"IMPORTANT: The statistical weight factor of the AIRES extended thinning algorithm is not equivalent to the param- 
eter with the same name defined for AIRES 1.4.2 or earlier. Therefore, the recommended values placed in the AIRES 1.4.2 
manual do not apply for the current version. 
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As it is well-known, there are still many open problems in this area and therefore the interaction 
models cannot be considered a crystallized part of the simulation programs. Furthermore, in the 
design of the interaction models and external packages units shown in figure [O] (page every effort 
was made to make them easily replaceable, in order to be able to incorporate improved code to be 
developed in the future. 

The IDL directives that are going to be mentioned in this section allow the user to control different 
model parameters. Such directives are defined from within the interaction model section, and for the 
reasons explained in the preceding pai^agraph, they are of a changing nature: For AIRES versions later 
than the current version 2.2.0 the model related directives may no longer be supported, be replaced 
by alternative ones or their syntax be totally or partially changed. 

3.4.1 External packages 

Both SIBYLL [|] and QGSJET [|] hadronic colhsions packages are implemented in AIRES 2.2.0. 
For technical reasons they are compile-time implemented, and are available by means of two different 
executable programs: Aires and AiresQ containing links to SIBYLL and QGSJET, respectively. 

All the particle-nucleus interactions with projectile kinetic energy above a certain threshold are 
processed using the external package, while the low energy ones are calculated by means of the Hillas 
splitting algorithm 

The IDL directive ExtCoIlModel is an On-Off switch that allows controlling the use of the exter- 
nal package (SIBYLL or QGSJET, depending on the executable program being used). The minimum 
energy required for the external package to be invoked can be altered using directive MinExtCoUEn- 
ergy, as in the following example: 

MinExtCollEnergy 30 GeV 

AIRES 2.2.0 supports the directive ForceModelName that is useful to ensure that a given input 
data set will be processed only with a determined simulation program. For instance, if an input data 
set containing the instruction 

ForceModelName QGSJET 

is processed with other simulation program different from AiresQ, the process will immediately 
be aborted with an error message. When the directive is not used no check is performed and the 
simulations can be started with any program. 

The cross sections used to determine the collision mean free paths can also be controlled. In the 
current version there are several sets of hadronic cross sections available, namely. Standard, Bartol 

QGSJET and SIBYLL cross sections. 

The default mean free paths are the ones corresponding to the external hadronic package linked 
to the simulation program, that is, the SIBYLL (QGSJET) set for program Aires (AiresQ). The 
following example illustrates how to alter the default settings: 

MFPHadronic Bartol 
MFPThreshold 12 GeV 



66 



Chapter 3. Steering the simulations 



These instructions imply that the "Bartol" mean free paths|^ will be used for collisions with energies 
over 120 GeV, while the standard mean free paths will be used for the ones with lower energies. 
The hadron-nucleus and/or the photon-nucleus collisions can be disabled if desired: 

NuclCollisions Off 
PhotoNuclear Off 

These settings are intended to be used only for special purposes: The results obtained in such condi- 
tions may be rather unphysical. 

3.4.2 Other control parameters 

There are several IDL instructions that allow controlling different parameters and/or processes of the 
simulation algorithms. These IDL directives need not be used for normal operation. Furthermore, the 
user should take into account that improper settings for some of the parameters associated with these 
instructions may lead to unphysical results. 

GammaRoughCut, ElectronRoughCut. Threshold energies for "normal" propagation of gammas 
and electrons, respectively. Particles with kinetic energies below those thr^esholds are "roughly" 
propagated, that is, many processes are calculated only approximately, or are ignored at all. 

LPMEffect. IDL switch to enable/disable the LPM [|l^, ^ effect. The default is LPMEffect On. 



DielectricSuppression. IDL switch to enable/disable the dielectric suppression [ ]17| , [23| ] effect. The 
default is DielectricSuppression On. 

HadronCutEnergy. A internal threshold energy for hadronic collision algorithms, used mainly in 
relation with Hillas splitting algorithm [p], |20|]. 

AirZeff, AirAvgZ/A, AirRadLength, HeavyMineko. IDL directives associated with internal pa- 
rameters. For a detailed explanation see appendix ^ (page 108). 



Since most of these IDL instructions are hidden directives (see page 55) the respective settings in 



effect will not be included in the input data list, unless explicitly indicated by means of directive In- 



putListing (see page 1 17). Additionally, warnings messages will be issued when using any directive 



which may lead to simulations with unphysical results. 



3.5 Special primary particles 

In many cases of interest, it is necessary to simulate showers that cannot be described adequately 
with the usual scheme of a single primary particle interacting with a nucleus in the atmosphere and 

'^IMPORTANT: Directives MFPHadronic and MFPThreshold replace tlie obsolete directives BartolMFP and Bar- 
tolThreshold, respectively, supported in AIRES version 1.4.2 or earlier. All input data sets containing those directives 
should be adequately modified. 
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generating a set of secondaries to be propagated. Instead, one has that a particular set of interac- 
tions that only affect the primary particle, originates a series of "normal" secondary particles that hit 
the atmosphere and originate the corresponding cascades. In general, such special interactions are 
not modeled adequately by AIRES propagating engine, but it is possible to overcome this difficulty 
allowing the simulation program to start a shower with multiple "primary" particles which are the 
secondaries coming out from the "special" interactions. 

The following are examples where the mentioned scheme applies: 

• An exotic cosmic particle (a cosmic neutrino, for instance) interacts and produces a series of 
particles that can be normally propagated by AIRES. 

• An electromagnetic particle interacts with the Earth's magnetic field before reaching the at- 
mosphere, and producing a pre-shower whose products finally reach the atmosphere and start 
interacting with it. 

• A cosmic particle disintegrates (before reaching the Earth) in two or more fragments that arrive 
simultaneously in slightly distant points. 

• Etc. 

AIRES 2.2.0 allows the user to simulate showers initiated in such conditions. An external, user 
provided, program will be responsible for generating the particles to be injected at the beginning of 
the shower. This process is completely dynamic, and the sets of generated primary particles may vary 
from shower to shower. 

To implement such an interface is very simple. The user needs to: (i) Define the special particle 
within the IDL instructions, (ii) Set up the external program that will be invoked (via a system call) 
at the moment of starting a new showers. 

3.5.1 Defining special particles 

The AIRES IDL directives allow to specify particles by names ("proton", "gamma", etc.). The set of 
known particle names can be expanded to include those special "particles" which need to be treated 
separately. 

Consider the following examples: 

AddSpecialParticle myparticX Xpartsim 
AddSpecialParticle myparticY Xpartsim type Y 

The IDL directive AddSpecialParticle takes at least two arguments: (i) A special particle name that 
uniquely identifies the added special particle, and (ii) The name of the executable module that will be 
invoked when starting the showers initiated by the respective particles. 

In the preceding example, two special particles, namely, myparticX and myparticY are defined 
and associated to the same external module, Xpartsim. In the case of the definition of myparticY, 
some arguments are specified (" type Y"). Such arguments are passed (portably) to the module. 
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Once the special particle(s) are definecQ, their names can be used as argument of the Primary- 
Particle directive: 

AddSpecialParticle myparticX Xpartsim 

PrimaryEnergy 20 EeV 
PrimaryParticle myparticX 



Special particles can also be used in the case of mixed composition (see page 58), like in the 
following example: 

AddSpecialParticle SSPl module.l 
AddSpecialParticle SSP2 module_2 

PrimaryParticle SSPl 0.2 
PrimaryParticle SSP2 0.3 
PrimaryParticle Proton . 5 

In this case the primary will be SSPl, SSP2, or proton with probabilities 20%, 30%, and 50%, 
respectively. 

3.5.2 The external executable modules 

Every time a special primary shower is started, the simulation program will invoke the executable 
module associated with the corresponding primary, defined using the AddSpecialParticle directive. 
Such an executable program can be a FORTRAN, C or C++ program (or a shell script running it), and 
must be capable of providing the calling module with the list of primary particles that will be added 
to the particle stacks before starting the simulation of that shower. 

The simulation program and the external module communicate via internal files in a way that is 
transparent for the user and completely portable. 

The AIRES object library includes a series of user-friendly routines (callable from FORTRAN, C 
or C++) that ease the task of writing such external modules. 



Figure 3.3 displays a brief FORTRAN program with the basic structure needed in every module 
capable of building a list of primary particles to start the simulation of a shower. 

The program starts with a call to routine speistart and ends with a call to speiend. It is essential 
to maintain this structure in any external module: All the calls to any AIRES library routine must be 
placed within the mentioned calls. 

Once the interface is started, the system is ready to accept primary particles that will be added to 
the primary particle list. The basic routine to add primaries to the list is spaddpO. For each invocation 
of this routine, the corresponding particle is added to the internal list of particles. There is no limit 
in the number of primary particles that can be included in the mentioned list, but the sum of their 
energies must not be larger than the primary energy specified in the input instructions and stored in 
the variable primary .energy appearing in figure 

''Up to ten different special particles can be defined for a given task. 
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c 

c An example of an external module to process "special" primary 

c particles. 

c 

program specialprimO 

c 

implicit none 

c 

c Declaration of variables retrieved when starting the interface 

c with the calling program, 

c 

integer 

double precision 
double precision 
double precision 
double precision 
double precision 

c 

integer rc 
double precision urandomt 

c 

c Some particle codes (AIRES coding system) . 

c 

integer pipluscode, piminuscode 

parameter {pipluscode = 11, piminuscode = -11) 

c 

c FIRST EXECUTABLE STATEMENT, 

c 

c Starting the AIRES-external module interface, 

c 

call speistart (shower_number, primary_energy , 
+ def ault_in jection_position, in jection_depth, 

+ ground_altitude, ground_depth, 

+ d_ground__in j , shower_axis) 

c 

c Injecting two particles at the initial injection point, and in 

c the direction of the shower axis. 

c 

el = primary_energy * urandomt ( . 05dO ) 
e2 = primary_energy - el 

c 

call spaddpO (pipluscode, el, 1, O.dO, O.dO, l.dO, l.dO, rc) 
call spaddpO (piminuscode, e2, 1, O.dO, O.dO, l.dO, l.dO, rc) 

c 

c Completing the main program-external module interchange. 

c The integer argument of routine "speiend" is an integer return 

c code passed to the calling program. means normal return. 

c 

call speiend(O) 

c 

end 



shower_number 
primary_energy 

def ault_in jection_position (3) 
in jection_depth, ground_depth 
ground_altitude, d_ground_inj 
shower_axis (3) 



Figure 3.3. A sample module for processing special primary particles. The purpose of this example 
is to illustrate the basic structure of a program to process the special primaries; the programmed 
algorithm is not intended to have any validity from the physical point of view. 



70 



Chapter 3. Steering the simulations 




Figure 3.4. The shower axis-injection point coordinate system, x'y' z' (magenta), contrasted with the 
AIRES coordinate system, xyz (green). The origin of the AIRES coordinate system, O, is located at 
sea level, while O' is located at the original shower injection point. Zg is the ground altitude. The 
2;'-axis is parallel to the shower axis, the x'-axis is always horizontal, and the y'z'-plane contains the 
z-axis. 



Arguments number 3 to 6 of routine spaddpO define the direction of motion of the corresponding 
particle. Argument number 3 is an integer switch selecting the coordinate system to use and the 
remaining quantities give the components of a vector, not necessarily normalized, pointing in the 
direction of motion of the particle. There are two options for argument number 3 (variable csys in the 



description of page 176) 



To select the AIRES coordinate system defined in section [2.1.1| (page 10). 

1 To select the shower axis-injection point system. This is a special coordinate system whose 
z-axis is parallel to the shower axis and its origin is placed at the original injection point (which 
remains uniquely determined by the shower zenith and azimuth angles and by the injection and 



ground altitudes). In this coordinate system, illustrated in figure 3.4, the coordinates (0, 0, z') 
and the vector (0, 0, 1) indicate, respectively, the position and direction of motion of a particle 
that moves along the shower axis and towards the ground. 

The process is completed with the call to speiend. This ensures that all the relevant variables are 
transmitted back to the main simulation program, which will recover the control after the external 
module ends. Both speistart and speiend must be called only once within the entire external module. 
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Notice also that one of the AIRES random number routines, namely, urandomt (see page |]J 
is used to evaluate the energy if the vr mesons being included in the list of primary particles. The 
random number generator is not initialized. Instead, its current status is passed by the main simula- 
tion program to the external module, and read-in within speistart. As a consequence, the generated 
random numbers will be different in different invocations of the external module. Routine speiend 
writes back the final status of the random number generator, and it is recovered by the main simula- 
tion program, so the numbers used in one and other program are always independent. If the AIRES 
random number generator is not used within the external module, then there are no alteration in the 
series of random numbers used by the main simulation program. 

An actual external module to process special primaries will surely be much more complex than the 
one of the preceding example. The user can provide special routines with the procedures needed for 
that purpose, and use routines from the AIRES object library as well. Many of the modules described 
in appendix ^ (page 133 ) can be used within special primary programs, in particular the ones directly 



related with the special particle interface system, which provide a set of tools covering the needs of 
the most common situations, namely: 

Retrieval of environmental information. Routine speistart starts the AIRES -external module in- 
terface and retrieves some basic variables, namely, shower number, primary energy, original 
injection position (three coordinates), vertical atmospheric depth of the original injection point, 
ground level altitude and vertical atmospheric depth, distance between the original injection 
point and the ground level (measured along the shower axis), and unitary vector in the direction 
of the shower axis. Besides these variables, it is possible (optionally) to retrieve additional ones 
calling other routines included in the AIRES object library: 



speigetpars (page |180| ) returns the parameter string that can be (optionally) specified in 
the IDL instruction that defines the corresponding special particle (see directive AddSpe- 
cialParticle, page |109| ). The simulation program passes the argument string directly, 
without making any special processing on it. 



speigetmodname (page 179) returns the name of the executable module specified in the 
definition of the con^esponding special particle. 

sprimname (page |186D returns the name of the special particle corresponding to the cur- 



rent invocation of the external module. 



speitask (page 1 84 ) returns the current task name. 



spnshowers (page |185[ ) returns three integers that correspond, respectively, to the total 
number of showers assigned to the task, and the numbers of the first and last showers. 
These quantities are related to the specifications entered with the directives TotalShowers 
and FirstShowerNumber. The variable shower .number set when calling speistart (see 



figure |3.3| ), will always be equal or larger (smaller) than the first (last) shower number. 



Adding primary particles to the primary particle list. Routine spaddpO appends to the particle 
list the particle defined with the arguments used in the corresponding call, as illustrated in 



72 



Chapter 3. Steering the simulations 



the example of figure 3.3. Additionally, there are two other related library routines available, 



namely, spaddpn (page |177D to append with a single call a set of various primary particles, and 
spaddnuU (page 175) to include null (unphysical) particles. A null particle is not included in 
the simulations, but its energy is added to the global null particle energy counter. Nuclei can 
be normally appended to the particle list. Nuclear codes can be conveniently evaluated using 
routine nuclcode (page |164| ). 

Changing the injection coordinates and time. After the initial call to speistart, the injection point 
is set to the original injection point defined by the global pai^ameters entered within the input 
data (zenith and azimuth angles, etc.). The coordinates with respect to the AIRES coordinate 
system of the original injection point are returned by speistart (this corresponds, in the example 



of figure 3.3, to array default Jnjection.position). The injection coordinates and time can be 



changed at any moment using routine spinjpoint (page 182). 



Setting the point of first interaction. When using normal primary particles, AIRES evaluates au- 
tomatically the atmospheric depth where the first major interaction takes place. This is not 
possible in the case of a special particle when a series of primaries are injected before starting 
the simulations; and the default action will be to set the first interaction at the original injection 
point, regardless whether that points corresponds or not to an actual point of interaction. As 
an alternative to the default action, it is possible to set manually the coordinates of the point 



of first interaction using routine splstint (page 174). Of course, this affects only the statistical 



analysis of the first interaction depth, and has no effect on the propagation of the particles. 
Version of external module. The user can assign a version number to the external module. This 



version number must be passed to the main program by means of routine speimv (page 181). 
The version number is stored with all the information associated with the current shower, in 
particular in the compressed output files. It is strongly recommended to assign version numbers 
to external modules that will be used in production simulations. 



We recall here that all the calls to every one of the routines listed in the previous paragraphs must 
be placed after the call to speistart and before the call to speiend. 
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4.1 Using the summary program AiresSry 

Every time a task is completed, the simulation programs invoke some output procedures that create a 
summary file displaying a series of results related with the already finished simulations. As it will be 
discussed in this section, there are several IDL directives that allow controlling such AIRES output 
data. 

The summary program, AiresSry, which is part of the AIRES system allows the user to process 
the simulation data contained within the internal dump file (IDF) or, equivalently, the portable dump 
file (ADF), and retrieve any of the available observables, similarly as the main simulation programs 
do. It is worthwhile mentioning that AiresSry can be used before as well as after the simulations are 
finished. In the first case it is possible to monitor the development of the simulation task while the 
former alternative is most convenient for analysis tasks. Backwards compatibility is always ensured: 
Old IDE's or ADE's generated with any previous version of AIRES can be processed normally using 
AiresSry .[] 

Many observables are of "tabular-" nature, that is, an array of data whose elements correspond to 
a set of values of a determined variable. Eor example, the longitudinal development of the number 
of gamma rays is represented by an an^ay whose elements give the number of gamma rays that have 
crossed the different observing levels, as a function of the observing level altitude. 

Most of the tabular observables commonly defined are automatically calculated by the simulation 
programs. The corresponding data aiTays ai^e stored in the IDE file and can be retrieved in several 
ways (see below). The complete list of currently available output data tables (more than 180) is 
placed in appendix S (page 128). 



'Notice, however, that a set of simulations created using a determined version of AIRES must be ended using the same 
version. 
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4.1 .1 The summary file 

The summary file (extension .sry) can be divided into two parts: (i) The general section, which 
includes data on the evolution of the simulations as well as some basic shower observables. (ii) 
Tables section, containing data tables accordingly to user's specifications. 

The summary file is generally written as a plain text file (this is the default). However, the 
IDL instruction LaTeX permits generating summaries that can be processed using the L?TeX type- 
setting system. If the I^TgX switch is enabled, then the AIRES system will generate two files, namely 
tasknamesry and taskname.tex. The last of these two files can be normally processed by a standard 
L?TeX system. 

On the other hand, it is also possible to instruct any of the AIRES programs not to write the 
summary file. To do this, just include the directive Summary Off into the input data stream. 

General section 

The general section of the summary file begins with computer related information (task and user 
identification, CPU time usage, etc.). It also includes information about the input parameters used, 
and reports on the number of particle entries processed at each stack. A complete report on stack 
usage can be obtained using the IDL directive 

Stackinf ormation On 

Then general information about the number and energy of particles reaching ground is displayed. 
For all the output observables, its mean^, standard deviation, root mean square enor of the mean, 
minimum and maximum, are reported. 

The IDL directive OutputListing Full will generate an additional section containing information 
(generally of computational nature) on several output quantities defined for different algorithms. 

The general section concludes with reports on the vertical depth of the first interaction, and on the 
location of the shower maximum. 

The data collected for the longitudinal development of all charged particles, that is, the number 
of charged particles Nc{i) that crossed the observing level i, for alH = 1, . . . , No, is used to estimate 
the shower maximum, Xmax> here defined as the vertical depth of the point where the number of 
charged particles reaches its maximum. The number of charged particles at the maximum, A^max is 
also evaluated. 

The estimation of the shower maximum is done by means of a 4-parameter fit to the Gaisser- 



^The statistical analysis is made in a shower-per-shower basis. 
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Hillas function 

max 

iVchW=iVmax(£^-^) exp( ^— ^ j, X>Xo. (4.1) 

^max, ^max, -'^o and A are the free parameters to be adjusted^. Notice that NchiXo) = 0,0 and that 
Nch{X) is taken as for X < Xq. 

A weighted nonlinear least squares fit performed with the aid of the very robust Levenberg- 



Mardquardt algorithm -as implemented in the public domain software library Netlib [|10|]- is done 
after the simulation of every individual shower is completed. The values reported in the summary file 
correspond to the plain average of all the fits with "reasonable" results (converged fits). The number 
of such converged fits is also reported. 

Tables section 



The output data tables listed in appendix ^ (page 128 ) that are automatically calculated during the 



simulations can be totally or partially included within the output summary file. An index of such 
tables can also be printed using the directive Tablelndex 

The PrintTables directive must be used to include one or more tables within the output summary 
file. Its syntax is shown in the following example: 

PrintTables 12 91 Options RM 

This instruction orders AIRES to "print" table 1291 (longitudinal development of all charged par- 
ticles) into the summary file. The options used are: R, to list RMS errors of the means, and M to 
include maximum and minimum data as numerical entries. For a detailed explanation of the directive 



PrintTables see page 122 



4.1.2 Exporting data 

An interesting feature of both the summary and the main simulation programs, is that they are able to 
generate output files containing any one of the tables listed in appendix ^ (page |128| ). Let us consider. 



^Our definition of the Gaisser-Hillas function involves vertical depths. Some authors, however, use slant depths instead. 
Both definitions can be used to parameterize the shower profile. Furthermore, notice that in the plane Earth approximation 
both "vertical" and "slant" forms are equivalent, provided the parameters are adequately interpreted, that is, taking into 
account the factor cos B of equation (E^. If the Earth's curvat ure is taken into account, the translations between vertical 
and slant quantities must be done numerically (see pages |l^ and 189). 



""in AIRES 1.2.0 a 3-parameter fit is made. A is kept fixed, with an externally given value of 70 g/cm^. The 4-parameter 
fitting algorithm currently used includes substantial improvements that increment the goodness of the fits for a variety of 
shower profiles whilst maintaining stable the fitting procedure. 

^The depth Xo refers to the point where the Gaisser-Hillas function is zero, and is not equal and not even necessarily 
related to the depth of the first interaction, noted Xi in this manual. 
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for instance, the following IDL instructions: 

Task mytask 

Svunmary Off 

Export 1205 1211 

Export 12 93 Option a 

Export 20 01 Options ds 

Export 2791 2793 Options ML 

End 

Here mytask is a string that represents an already finished or currently running task. The Summary 
Off directives disables the summary file. This is, of course, optional, but might be useful when the 
user is just interested in creating table files. 

The first ExportTables directive (the abbreviated name will be correctly interpreted by any of the 
AIRES main programs) indicates that all the tables whose numbers are in the range [1205, 1211] must 
be exported with the default options. Looking at the listing in appendix ^ (page 128), it comes out 
that the involved tables are tables number 1205, 1207 and 1211. 

The second export directive instruct AIRES to export table 1211 with the option of listing the 



slant depths of the observing levels, that is, measured along the shower axis (equation (|2.8|)). By 
default (Option r) all atmospheric depths listed within exported tables are vertical depths. 

In the second export directive, the option string ds modifies the default settings, d indicates 
that the particle numbers must be normalized to particle densities, expressed in particles/m^ ; and s 
suppresses the file header (only the tables will be written). This last option may be useful when the 
exported files ai^e read by other applications (piped). Suppressing the file header, however, may lead 
to not understandable files, especially if they are not processed at the moment they are produced. It is 
therefore recommended to always keep such information; and it must be also taken into account that 
all the header lines are "commented out" by means of a leading comment character which defaults to 
"#", but can be changed by means of the directive CommentCharacter (see page |1 1 1[ ). 

In the last example, the energy distributions 2791, 2792 and 2793 ai^e exported. The option M 
indicates that energies must be expressed in MeV (the default is GeV); while indicates that the cor- 
responding data are normalized to dN/d\ogiQ E distributions. The alternative option 1 corresponds 
to dN/ dlnE normalization. 

To process the preceding code, it might be useful to edit a small text file containing them and then 
use -for instance- the summary program to process it: 

AiresSry < myfile.inp 

The files mytask.tl205, mytask.tllOl , . . . , etc., will be created. If such files already exist, they will 
be overwritten. 

If the simulations that generated the data being processes were run with the PerShowerData op- 



tion Full (see section 3.3.6), then it is possible to export single shower tables by placing the directive 



*The options IL were not supported in AIRES 1.2.0. 
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ExportPer Shower 

together with the ExportTables one(s). Returning to our previous example, if such directive is placed 
inside the file myfile.inp, then for each one of the exported tables, the files 

mytask.tnnnn 

mytaskjsOOOl.tnnnn 

mytaskjsOOOl.tnnnn 

will be created, corresponding respectively to the usual average table, and the tables for shower 1, 2, 
etc. 

4.2 Processing compressed particle data files 

Like other simulation systems [|l|, |2^, AIRES can produce output files containing detailed infor- 
mation about the particles generated during the simulations. The well-known fact that that detailed 
information generates huge amounts of data has been especially taken into account in the design of 
AIRES, which includes an ad hoc data compressing algorithm to save file space. 

A detailed explanation of the compressing algorithm -a rather technical matter- is beyond the 
scope of this manual. We shall limit ourselves to briefly list its main characteristics: 

Format. The compressed files are plain text files that can be generated in any computer and copied 
and processed in any other one. This is valid even if the machines do not have the same oper- 
ating system and/or do not use the same character codes (for example non-ASCII machines). 

Organization. The files contain a header with data related to its structure and the conditions of the 
simulation. The particle data section represents the bulk of the file and, in general, the records 
corresponding to any one of the simulated showers are delimited by "beginning of shower" and 
"end of shower" records. There is practically no limit in the number of showers that can be 
included in a single file.|] On the other hand, groups of showers can be saved into separate files, 
up to the limit of storing each shower in a different file (see page |125| ). 

Compression rate. The data compression algorithms were designed to take profit of the physical 
properties of the quantities being stored. This involves information about lower and upper 
bounds for a variable, possibility of subtracting a given fixed value|^ etc. Precision requirements 
were also taken into account, imposing a minimum of five significant figures in most cases. 
To give an idea of the size of compressed records, let us consider the default ground particle 
record (see below) whose fields are: Particle code, logarithm of the energy, logarithm of the 
distance to the core, polar angle in the ground plane, arrival time, x and y components of the 

'it is possible to store up to 759375 showers in a single compressed file. 
^This refers to internal operations which do not alter any user-level results. 
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direction of motion, and statistical weight. This record thus has one integer field and six real 
ones, and its length is 18 characters (bytes). This figure should be contrasted with a standard 
FORTRAN internal write statement with single precision for real variables, which generates 28 
data bytes when writing the same fields. Taking into account that such records usually include 
additional formatting fields, the compression rate of AIRES algorithm compared with standard 
unformatted FORTRAN i/o should be larger than 36%. 

It is worthwhile mentioning the the AIRES package includes a library of subroutines, namely, 
the AIRES object library, which contains many routines to read and process the compressed output 
files. Backwards compatibility is always ensured: Old compressed files generated with any previous 
version of AIRES can be read normally using the library routines. 

4.2.1 Customizing the compressed files 

Two kinds of compressed files ai^e implemented in the current version of AIRES (2.2.0): 

Ground particle file. (Extension .grdpcles) This file contains records with data of particles that 
reached the ground surface. 

Longitudinal tracking particle file. (Extension .Igtpcles) Compressed file containing detailed data 



related with particles crossing the predefined observing levels (see section 13). 



Ground particle file 

There are three basic types of data records in this file: "Beginning of shower" record, "end of shower" 
record and particle record (also referred as default record). The "external primary particle" and "spe- 
cial primary trailer record" are also defined. These last two records are used only in connection with 



the special primary particles described in section |3^ (page |66|) 



All the particle records written out during the simulation of a single shower will appear in the file 
preceded by a beginning of shower record, and followed by the corresponding "end of shower" one. 



The fields that make the beginning (end) of shower record are listed in table 4.1 (4.2). Tables 4.3 



and ^j4| describe the fields of the special primary related records. In these and in any other records, 
the data fields can be classified in integer and real fields. 

The fields contained in such delimiting records account for general air shower parameters or 
observables and were included for special analysis tasks. 

In the case of showers initiated by special primary particles (see section ^3| ), the "Primary parti- 
cle" code of the corresponding "beginning of shower" record will not correspond to a standard particle 
code. Instead, the returned code will be a negative integer with an absolute value slightly smaller than 
100000.PI 



'The library routine crospcode is the adequate one to manage such special particle codes. 
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Integer 



Real 



Field Name 

1 Primary particle code 

2 Shower number 



3-8 Starting date and time 



1 Primary energy (GeV) (log) 

2 Primary zenith angle (deg) 

3 Primary azimuth angle (deg) 

4 Thinning energy (GeV) 

5 First interaction depth (g/cm2) 

6 Central injection altitude (m) 

7 Global time shift (sec) 



Description 

Stores the code of the primary particle. 
Shower number. By default, the first 
shower is labelled with the number 1, but 
the user can manually set the first shower 
number by means of the IDL directive 



FirstShowerNumber (see page |1 14[ ). 
Six fields containing, respectively, the 
year, month, day, hours, minutes and 
seconds corresponding to the beginning 
of the simulation of the corresponding 
shower. 

The logarithm of the primary particle's 
energy. 

The zenith angle of the primary particle. 
The azimuth angle of the primary parti- 
cle. 

The absolute thinning energy used for 

the respective shower. 

The vertical depth of the point where the 

first interaction took place, Xi. 

The z-coordinate of the primary's injec- 



tion point (see figure 2.1). 



The time to required for a particle mov- 
ing along the shower axis at the speed 
of light, to go from the injection point to 
the ground level. 



Table 4.1. Fields contained in the "beginning of shower" record of compressed particle files. The 
structure of this record does not depend on the compile-time option selected for the particle record. 

In those cases, the "beginning of shower" record will be followed by a series of "external primary 
particle" records (one for each injected primary particle). This series ends with a "special primary 
trailer record" which will precede the default particle records written for that shower. 

The fields included in the default records, associated with particle data, can be selected at compile 
time among the various available alternatives. The installation configuration file (see appendix ^ 
contains detailed instructions on how to select the particle record options. 

The most relevant physical properties of the ground particles can be saved in the ground com- 
pressed file, namely. 

Particle code. An integer code that identifies the particle. 
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Field Name 

Integer 1 Shower number 

2 Xmax fit return code 

3-8 Ending date and time 

Real 1 Total number of shower particles 

2 Total number of lost particles 



3 Number of low energy particles 



4 Number of particles reaching 
ground 



5 Total number of unphysical 
particles 



6 Total number of neutrinos 



7 Particles too near to the shower 
core 

8 Particles in the resampHng region 



Description 

Shower number (matching the shower 
number of the corresponding "beginning 
of shower" record). 

Integer code returned by the Xmax and 
Njaax fitting routine described in section 
0(page^. 

Six fields containing, respectively, the 
year, month, day, hours, minutes and 
seconds corresponding to the end of the 
simulation of the corresponding shower. 

Total number of particles processed dur- 
ing the simulation of the corresponding 
shower. 

Total number particles that went outside 
the region of interest for the simulations. 
Total number of particles whose kinetic 
energies fell below the corresponding 
thresholds. 

Total number of particles that reached 
the ground level, including also those 
particles not saved in the compressed 
file. 

Number of "particles" generated by spe- 
cial procedures -like the splitting algo- 
rithm, for example- which cannot be as- 
sociated with physical particles. This 
number is generally very small. 
Total number of neutrinos (i/g, z/g, f^, 
Ufj,) generated during the simulation of 
the current shower. 

Number of particles that were not saved 
in the compressed file because they were 
too near to the shower axis (see text). 
Number of particles that were processed 
with the resampling algorithm (see text). 



Table 4.2. Fields contained in the "end of shower" record of compressed particle files. The structure 
of this record does not depend on the compile-time option selected for the particle record. 
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Field Name 

Real 9 Paiticles too far from the shower 
core 

10 Shower maximum depth (Xmax) 
(g/cm2) 



1 1 Total charged particles at shower 
maximum 

12 Energy of lost particles (GeV) 

13 Energy of low-energy particles 

14 Energy of ground particles (GeV) 

15 Energy of unphysical particles 
(GeV) 

16 Energy of neutrinos (GeV) 

17 Energy lost in the air (GeV) 



18 Energy of particles too near to the 
core 



19 Energy of resampled particles 



20 Energy of particles too far from the 
core 



Description 

Number of particles that were not saved 
in the compressed file because they were 
too far from the shower axis (see text). 
Vertical depth of the point where the 
number of charged particles is maxi- 
mum, Xjnax> obtained from a fit to the 
simulation data (see section p~l| ). 
Number of charged particles at Xmax, 
-^max> calculated as explained in section 



21 CPU time (sec) 



O](page0). 

Total energy of the particles of real field 
number 2. 

Total energy of the particles of real field 
number 3. 

Total energy of the particles of real field 
number 4. 

Total energy of the particles of real field 
number 5. 

Total energy of the particles of real field 
number 6. 

Total amount of energy lost by contin- 
uous medium losses (ionization losses) 
due to charged particles moving through 
the air. 

Total energy (in GeV) of the particles of 
real field number 7. This field is not de- 
fined for the longitudinal tracking parti- 
cle file. 

Total energy (in GeV) of the particles of 
real field number 8. This field is not de- 
fined for the longitudinal tracking parti- 
cle file. 

Total energy (in GeV) of the particles of 
real field number 9. This field is not de- 
fined for the longitudinal tracking parti- 
cle file. 

Amount of processor time required for 
the simulation of the current shower. 



Table 



4.2 



( continued) 
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Field Name 

Integer 1 Particle code 

Real 1 Energy (GeV) (log) 

2 Direction of motion (x component) 

3 Direction of motion (y component) 

4 Direction of motion (z component) 

5 X coordinate (m) 



6 Y coordinate (m) 

7 Z coordinate (m) 

8 Injection depth (g/cm2) 

9 Injection time (ns) 
10 Particle weight 



Comment 

Stores the code of the corresponding pri- 
mary particle. 

The logarithm of the coiTcsponding pri- 
mary particle's energy. 
With respect to the AIRES coordinate 
system (see page p^). 



Particle injection coordinate, with re- 
spect to the AIRES coordinate system 
(see page II( 



Initial statistical weight of the corre- 
sponding particle. 



Table 4.3. Fields contained in the ''external primary particle" record of compressed particle files. 
The structure of this record does not depend on the compile-time option selected for the particle 
record. 



Field Name 

Integer 1 Version of external module 

Real 1 Total number of primaries 

2 Unweighted primary entries 

3 Total energy of primary paiticles 
(GeV) 



Description 

User-settable integer in the range 
[0,759375]. 

Total number of primary particles. 
Unweighted number of primary entries. 
Total energy of primary particles 
(weighted). 



Table 4.4. Fields contained in the ''special primary trailer record" of compressed particle files. The 
structui^e of this record does not depend on the compile-time option selected for the particle record. 
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Integer 
Real 





Field 




Short 


Normal 


Long 


1 


1 


1 


1 


1 


1 


2 


2 


2 


3 


3 


3 




4 


4 




5 


5 


4 


6 


6 


5 


7 


7 






8 
9 



Paiticle code 

Energy (GeV) (log) 

Distance from the core (m) (log) 

Ground plane polar angle (radians) 

Direction of motion (x component) 

Direction of motion (y component) 

Arrival time delay (ns) 

Particle weight 

Particle creation depth (g/cm2) 

Last hadronic interaction depth (g/cm2) 



Table 4.5. Fields contained in the particle records of compressed ground particle files. The field 
numbers for the different particle records selectable at compilation time (see text), named short, 
normal and long records, are tabulated. Notice that a given field can have different field numbers. 



Energy. The logarithm of the kinetic energy of the particle. 

Coordinates. The polar coordinates {R, ip) of the particle at ground, measured from the intersection 
of the shower axis with the ground surface. R is the distance to the core and cp is the angle with 
respect to the x-axis. 

Direction of motion. The x and y components, Ux, Uy, of the unitary vector u which indicates the 
particle's direction of motion. The Uz component must be negative for the particles reaching 
ground because such particles move downwards. It can be calculated via: 



l-u^-ul (4.2) 
Arrival time. The saved quantity is the arrival time delay t — tQ, where t is the absolute time (mea- 



sured from the beginning of the shower), and to is the global time shift described in table ^ 
(page 



Particle weight. The statistical weight of the particle (see section 2.3). 

Creation depth. The vertical atmospheric depth of the point where the particle was inserted into the 
simulating program's stacks. 

Last hadronic depth. The vertical atmospheric depth corresponding to the last hadronic interaction 
suffered by the particle or by one of its ancestors. 

For each one of these quantities, a corresponding record field is defined. The complete list of 
fields is placed in table 4.5 (page 83). As mentioned previously, there are several record formats each 
one including a different subset of aU the available fields. 



84 



Chapter 4. Managing AIRES output data 



In contrast with the beginning of shower and end of shower records, a given field of the particle 
record can be assigned different field numbers. As it will be seen below in this chapter, this does not 
affect the user's processing of compressed files, which can be done independently of the field number 
assignments. 

There are specific IDL directives that can control the particles that are actually saved in the ground 
particle file. 

To start with, let us consider the directives RLimsFile and ResamplingRatio, whose syntax is 

RLimsFile grdpcles rmm ^^max 
ResamplingRatio Sr 

grdpcles identifies the file the directive refers to and rmin and r^ax represent length specifications 
(0 < Tmin < r-max)- -Sr is a real number (sr > 1). 

Such directives instruct AIRES to save unconditionally those particles whose distances to the 
shower axis lie within the interval [rmin , r^ax] ■ 

On the other hand, aU the particles whose distances to the shower axis are smaller than 

ro = ^— (4.3) 

(ro is, by definition, not larger than r^nm) are not included in the ground file, but their number and 
energy are recorded and the totals are included in the "end of shower record" (fields 7, 9, 18, and 20). 

Finally, all the particles whose distances r to the shower axis lie in the interval [ro , rmin] are 
processed by a resampling algorithm which conditionally keeps the particles accordingly with the 
following rules: (i) "Nonnumerous" particles -like pions, nucleons, etc.- are always saved, (ii) For 
every "numerous" particle -i.e., gammas, electrons, positrons and muons- in the mentioned region, 
the acceptance probability i^ 

Ps=(^y. (4.4) 

(iii) The statistical weights of the accepted particles are increased via 

w' = -, (4.5) 

Ps 

in order to keep unbiased the sampling algorithm. 

The total number and energy of particles that fall within the resampling area, ai^e recorded in the 
"end of shower record" (fields 8 and 19). 

The SavelnFile (SaveNotlnFile) directive permits including (excluding) one or more particle 



kinds into (from) the compressed file. Section 3.2.5 (page 47) contains several illustrative examples 
on how to use them. 

Notice that by default, all particle kinds are enabled to be saved into the ground particle file. 



"The expression of the acceptance probability is inspired in a suggestion by P. Billoir [^]. 
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Field 

Short Norm. Norm. Long 







fa) 






Integer 


1 


1 


1 


1 




2 


2 


2 


2 


Real 




1 




1 








1 


2 








2 


3 




1 


2 


3 


4 




2 


3 


4 


5 




3 


4 


5 


6 




4 


5 


6 


7 



Extra- 
long 



1 


Particle code 


2 


Observing levels crossed 


1 


Energy (GeV) (log) 


2 


Direction of motion (x component) 


3 


Direction of motion (y component) 


4 


Particle weight 


5 


Crossing time delay (ns) 


6 


X coordinate (m) 


7 


Y coordinate (m) 


8 


Particle creation depth (g/cm2) 


9 


Last hadronic interaction depth (g/cm2) 



Table 4.6. Fields contained in the particle records of compressed longitudinal tracking particle files. 
The field numbers for the different particle records selectable at compilation time (see text), named 
short, normal (a), normal (b), long and extra-long records, are tabulated. Notice that a given field 
can have different field numbers. 



Longitudinal tracl<ing particle file 

The structure of the longitudinal tracking particle file is very similar to the already described ground 
particle file: Both files have virtually the same "beginning of shower", "end of shower", "external 
primary particle", and "special primary trailer" records; and there are alternative formats for the 
particle records. 

For that reason, it is highly recommended to the reader be familial" with the contents of the previ- 
ous section describing the ground particle file before proceeding to read the present section. We shall 
limit here to briefly describe only those aspects that are somehow different in both files. 

The longitudinal tracking particle file contains records storing detailed information about the 
particles that cross the defined observing levels. Since the observing levels are generally located at 
altitudes that include the shower maximum, and due to the fact that a single particle can cross more 
than one observing level during its life, it is clear that the longitudinal files can potentially be much 
larger than the average ground particle files. 

For that reason, a special effort was made to save as much space as possible, and various record 
formats were defined to allow the user to select just the necessary fields. The record format selection 
can be done during installation, following the instructions placed in appendix ^ (page 103). Table 



4-.6| (page |85|) lists all the defined data fields for the different default records. 

The second integer field, named "Observing levels crossed" contains information about the ob- 
serving levels the particle has crossed, and simultaneously about its direction of motion. 

Let No {No < 510) be the number of defined observing levels. At a certain monitoring operation. 
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a given particle crosses several observing levels from level ij to level ii {ii may be equal to if). Let 
Uz be the z-component of the particle's direction of motion. If ii^ > (uz < 0) the particle goes 
upwards (downwards), and therefore if >ii (if < ii). 

All this information is encoded in a single integer number called the crossed observing levels key, 
L, defined by the following equation: 

L = if + 512 ii + 512"^ Snd (4.6) 

where 

/ 1 if -"^ > 

^"^ = \ if^.<0 ^^-^^ 

The three variables that appear in the right hand side of equation ( |4.6| ) can be easily reconstructed 
when L is known (see page 94). 

The real fields listed in table 4^ (page 85) are defined similai^ly to the con^esponding ground 
particle record fields, with the exception of the x and y coordinates which are defined as follows: 

Coordinates. The {x, y) coordinates are the Cartesian coordinates of the point where the particle 
crossed the level if, measured from the intersection between the shower axis and the cor- 
responding observing level's surface. 

Time delay. Defined as the difference t — tf where t is the particle's absolute time and is the 
time required for a particle moving along the shower axis at the speed of light to go from the 
injection point to observing level if. 

The IDL directives RLimsFile, ResamplingRatio, SavelnFile and SaveNotlnFile can be used 
with longitudinal files to control when a particle must be saved or not. The last two directives do not 
present special difficulties, and work as explained in section 3.2.5 (page pT] ). 

On the other hand, the directives|^ 

RLimsFile Igtpcles rmin ?^max 
ResamplingRatio 

define three parameters, rmin, '"max and Sj., that are used to determine whether a particle record must 
be saved or not. The rules are the following: 

1. Let Xc = 0.8 + 0.2 Xg, where Xi and Xg ai^e the vertical injection and ground depths, 
respectively. 

2. For each observing level i, i = 1, . . . , No, let 



if x'i^ < Xc 



■^o — -^c 

Xg- Xc 



if Xc < X« < Xg (4-8) 



if X^'^ > Xg 



"Notice that the parameter controlled by directive ResamplingRatio is global, that is, its last setting applies to every 
one of the compressed files in use. 
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where Xq'^ is the vertical depth of observing level i; and let vqi = rij Sr- 

3. Any particle crossing observing levels will not be saved in the longitudinal file if one of the 
following conditions is true: 

(a) < roi and \y\ < roj. 

(b) \x\ > 

'"max or \ y\ > Tjiiax- 

X and y are, the Cartesian coordinates of the particle at observing level if, measured from the 
intersection between the shower axis and the corresponding observing level. 

4. Gammas, electrons, positrons and muons crossing observing levels and verifying the two fol- 
lowing conditions 

(a) |x| < rmin and \y\ < rmm- 

(b) |x| > roi or \y\ > roj. 

(in the same notation of the previous point), will be conditionally kept, with probability and 



reweighting factor given by equations (4.4) and (4.5), respectively. 



5. All the particles not fulfilling the conditions of the preceding points will be unconditionally 
saved in the file. 

These rules set varying limits for the zone of excluded particles. In the zone neai" the shower axis, 
all particles crossing observing levels placed above Xc will be saved, then the exclusion zone enlai^ges 
proportionally to the depth of the observing level, reaching the value indicated in the RLimsFile 
directive at the ground depth. Notice that Xc divides the complete shower path (as measured in 
atmospheric depth) into two, upper-lower, 20%-80%, zonesj^ 

The number of defined observing levels affects the degree of detail of the monitoring of the 
longitudinal shower development, and some applications usually require that this number be as large 
as possible. On the other hand, such setting may lead to the generation of very big longitudinal particle 
files since a large number of data records are generated as long as every particle crosses the observing 
levels. To overcome this difficulty, AIRES includes a selection mechanism to avoid including in the 
compressed file the information related with all the defined observing levels. Consider the following 
illustrative example: 

ObservingLevels 100 
SavelnFile Igtpcles e+ e- 
RecordObsLevels None 
Re CO rdObs Levels 1 
Re CO rdObs Levels 4 
RecordObsLevels 10 9 10 
RecordObsLevels Not 2 



'^The present figures modify the 40%-60% zones used in AIRES 2.0.0 or earlier. 
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The first directive sets the number of observing levels to 100, and the second one enables particle 
saving in the longitudinal particle tracking file. In this case only electrons and positrons will be 
recorded (Notice that the longitudinal file is disabled by default, and therefore it is necessary to use 
unless one SavelnFile instruction to enable it). The default action is to record particles crossing 
any of the defined observing levels, and the remaining instructions are placed to override this default 
setting. The directive RecordObsLevels None eliminates all the defined observing levels from the 
set of levels to be taken into account to save particle records into the compressed file. The actions of 
the instructions that follow are, respectively: Mark level 1 for recording particles crossing it; idem 
level 4; idem all levels from 10 to 90 in steps of 10 levels; unmark level 20. The resulting set of 
marked levels is {1, 4, 10, 30, 40, 50, 60, 70, 80, 90}. 



4.2.2 Using the AIRES object library 

The AIRES object library is a set of routines designed with the main purpose of providing adequate 
tools to analyze the data saved in the compressed output files. 

Appendix ^ (page 133) explains in detail the contents of the library and how to use it. In this 



section some illustrative examples are presented. 

From now on we are going to assume that the AIRES file is being processed by a program, 
provided by the user and similar to the demonstration programs that are included with the AIRES 
software distributions. 

We are going to use FORTRAN in our examples, but this is not a restriction since the AIRES 
library includes routines for a C interface, which allow the C user to fully exploit the library's re- 
sources. 



Output particle codes 

Every analysis program must begin with a call to routine ciorinit. This routines sets up the environ- 
ment where the library routines can work adequately. 

This routine permits setting the particle coding system that the user wants to work with. It is 
possible to select either the AIRES coding system already described in section 2.2.1 (page 19), or 
other usual coding systems. The coding systems known by AIRES 2.2.0 are the following: 

1 . Aires internal coding. 

2. Aires coding for elementary particles and decimal nuclear codes (A + 100 Z). 



3. Particle Data Group coding system [30], extended with decimal nuclear codes (A + 10 Z). 



4. CORSIKA simulation program particle coding system []28[]. 

5. GEANT particle coding system [pl|]. 

6. SIBYLL [^] particle coding system, extended with decimal nuclear codes (A + 100 Z). 
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Particle Codes 







pri/7 

lUKj 




riJ7 A AIT 






7 


1 


22 


1 


1 


1 


1 


1 


2 


-11 


2 


2 


2 


2 


e~ 


-2 


11 


3 


3 


3 


-2 




3 


-13 


5 


5 


4 


3 




-3 


13 


6 


6 


5 


-3 


1 


4 


-15 


86 


86 


20 


10 




-4 


15 


87 


87 


-20 


-10 




6 


12 


66 


4 


15 





Ve 


-6 


-12 


67 




16 







7 


14 


68 


4 


17 







-7 


-14 


69 




18 







8 


16 


4 


4 









-8 


-16 













10 


111 


7 


7 


6 


5 


7r+ 


11 


211 


8 


8 


7 


4 




-11 


-211 


9 


9 


8 


-4 




12 


310 


16 


16 


12 


12 


K 


13 


130 


10 


10 


11 


13 


K+ 


14 


321 


11 


11 


9 


11 


K- 


-14 


-321 


12 


12 


10 


-11 


V 


15 


221 


17 


17 


22 


14 


n 


30 


2112 


13 


13 


14 


6 


n 


-30 


-2112 


25 


25 


-14 


-6 


P 


31 


2212 


14 


14 


13 


7 


P 


-31 


-2212 


15 


15 


-13 


-7 



Table 4.7. Elementary particle codes coiTcsponding to several commonly used coding systems. The 
routines that process AIRES compressed output files allow the user to select any one of these coding 
schemes. 
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7. MOCCA-style particle codes [|I|], extended to match all AIRES particles[3. 
The codes corresponding to elementary particles are listed in table |4.7[ . 

Opening existing flies 

Once the proper environment is set up by means of the initializing routine, the system is ready to 
open any existing compressed file. The open routine opencrofile will use the header information to 
initialize the internal variables that permit processing the different fields defined for the file. The 
following example illustrates how to open a file: 

program sample 
character*80 mydir, myfile 
integer channel, ire 

call ciorinit(0, 1, 0, ire) 

call opencrofile (mydir, myfile, 0, 10, 4, channel, ire) 

myfile and mydir are character strings containing respectively the file name and the directory where it 
is placed. The integer argument "10" indicates that the logarithmic fields are going to be transformed 
into decimal logarithms, channel is an output pai^ameter identifying the opened file; it should not be 
set by the calling program. 

It is important to remark that this call will transparently open any compressed file, regardless of 
its type or format (ground particle as well as longitudinal tracking particle files in all their variants), 
the AIRES version used to write it and/or the machine used when writing it. 



Getting information about thie fiie 

The headers of the compressed files are divided into two parts: One part containing the definitions of 
the file's data records and another section with information about the simulations that originated the 
file. 

The file definitions are specific to each opened file, and therefore the system must store them 
separately for each one of the files that are simultaneously open. 

The other information, however, is of global character, and so the available data always corre- 
sponds to the last opened file. These data are superseded each time opencrofile is called. 

Routine croheaderinfo prints a summary of this global information while croinputdataO copies 



some of those data into arrays to make them available to the user (see page |143| ) and crotaskid returns 
task name information. Functions getinpint, getinpreal, getinpstring and getinpswitch (see pages 
158| - 161 ) allow to obtain other input data items not returned by croinputdataO. idlcheck returns 



'^Actually, MOCCA does not use particle codes. Instead, particles are identified by types (1 gamma, 2 electron, 3 muon, 
etc.) and charge (0, ±1, etc.). Our MOCCA-style codes emulate this coding system generating particle codes by joining 
the sign of the charge and the particle type. 
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information about the IDL instructions that were valid when the file was generated, and crofileversion 
and thisairesversion return version information that might be useful when reading compressed files 
written with old AIRES versions. 

The structure of any already opened file can be printed calling routine croflleinfo which prints 
a list of the different records defined for the corresponding file and the names of the fields within 
records. 

Reading the data records 

Once a file is open, it remains positioned at the beginning of the compressed data section. From then 
on, the file can be sequentially read using routine getcrorecord: 

okflag = getcrorecord { channel , indata, fldata, altrec, 

0, ire) 



getcrorecord returns logical data, which in this case are stored in the logical variable okflag. The 
returned value is "true" if the reading operation was completed successfully, "false" otherwise (end 
of file, I/O eiTor, etc.). 

ciochann should be the same integer variable used when opening the file; it identifies the file to 
be processed. 

ire is an integer return code. If okflag is "false", then the return code contains information about 



the error that generated the abnormal return, as explained in page 155. For successful read operations, 
ire indicates the record type that has been just read in: for the default particle record, 1 (2) for the 
"beginning (end) of shower" record, etc. At the same time, the logical variable altrec distinguishes 
between "alternative" (non default) records (true), from default ones (false). 

The data stored in the different fields of the record is retrieved by means of the arrays indata and 
fldata. Both are single index anays, containing integer and double precision data, respectively. The 
data items stored in these an^ays does vary with the kind of file being processed and the type of record 
that was scanned. In all cases, the routine will automatically set the relevant elements of these arrays 
accordingly with the logical definition of the record, regardless of the physical structure of it which 
remains absolutely hidden at the user's level. 

To fix ideas, let us suppose that a ground particle file with normal particle records is being pro- 
cessed. Every time ire is zero (default record), the integer and real data arrays will contain the 



elements listed in table (page |83|), that is 

indata ( 1 ) <— Particle code 

fldata (1 ) ^ Energy (GeV) (log) 

fldata (2) ^ Distance from the core (m) (log) 

fldata (3) <— Ground plane polar angle (radians) 

fldata ( 7 ) ^ Particle weight 
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For different return codes, the number of assigned array elements may be different, as well as 
their meanings; but in all cases such data items will be set accordingly with the corresponding record 
sequence (tables p~T| , p^ , etc.). 

In order to make the analysis programs simpler and more robust, a special routine has been in- 
cluded in the AIRES library to automatically set the adequate field indices corresponding to a given 



record of a certain compressed file, as illustrated in the example of figure 

The outstanding characteristic of this piece of code is that the elements of an^ays indata and 
fldata are not referenced directly using numeric indices, but by means of integer variables like icode 



for instance (see figure 4. 1 ) 



Those index variables are set by means of routine crofieldindex. The arguments required by this 
routine include: (i) The identification of the file (channel), (ii) The record type, coincident with 
the return codes of getcrorecord akeady mentioned. In this example for the default record and 2 
for the "end of shower" record, (iii) The first characters of the field name. Fields are identified by 
their names, providing therefore absolute transparency to the fact that the order and number of fields 
may change with the file being processed. The next argument of crofieldindex is set to 4 to force 
the program to stop in case of ambiguous or erroneous field specification, thus providing a very safe 
processing environment, (iv) The output argument datype returns information about the data type 



corresponding to the specified field, as explained in page 137 



Closing files and ending a processing session 

The AIRES library routines support simultaneous processing of more than one compressed file. Sev- 
eral compressed files can be opened at the same time, each one identified by the corresponding chan- 
nel integer variable. 



The opened files can be closed using two alternative procedures (see page |134[ ): (i) Routine 
cioclosel closes individual files, cioclose closes all the cuiTcntly opened files. 

Routine cioclose should be used only if the processing session will continue after closing all files. 
To finish an analysis program in an ordered fashion use the routine ciorshutdown. This procedure 
performs all the required tasks to properly set down the processing system, including a call to cioclose. 

Other operations 

There are many other routines included in the AIRES library that provide useful tools for special 
analysis tasks. Such routines are explained in detail in appendix ^ (page 133), we shall limit here to 
a brief presentation of the most relevant ones: 

Counting records. Routines crorecinfo and croreccount count the data records contained within a 
compressed file. 

Repositioning. Routine crorewind repositions an already opened file at the beginning of the data 
section. Routines crorecnumber and crogotorec, used jointly, permit accessing the data 
records in arbitrary order. 
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program sample 

integer datype, ire, icode, idist, inear 

integer indata(30) 

double precision fldata(30) 

integer particlecode 

double precision logdistance, numberofnear 
call ciorinit(0, 1, 0, ire) 

call opencrofile (mydir, myfile, 0, 10, 4, channel, ire) 



icode = crofieldindex (channel, 0, 'Particle code', 

4, datype, ire) 
idist = crofieldindex (channel, 0, 

'Distance from the core', 

4, datype, ire) 
inear = crofieldindex (channel, 2, 'Particles too near', 

4, datype, ire) 



okflag = geteroreeord (channel, indata, fldata, altrec, 0, 

ire) 

if (ire .eq. 0) then 

particlecode = indata (icode) 
logdistance = fldata (idist) 

else if (ire .eq. 2) then 

numberofnear = fldata (inear) 

end if 



Figure 4.1. Processing compressed data files, an example illustrating how to set field indices 
automatically. 
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Fast scanning of a file. Routine crorecfind finds the next appearance of a record of a given type (to 
locate shower headers, for example), getcrorectype returns the type of the next record, and 
regetcrorecord re-reads the current record. 

Longitudinal tracking file utilities. Routine crooldata returns basic information about the positions 
of the observing levels defined for the simulations; while olcoord returns the coordinates of the 
intersections between the observing levels and the shower axis and olv2slant evaluates the slant 
depths corresponding to each observing level. Routines olcrossed and olcrossedu decode the 



crossed observing levels key defined in equation (4.6), returning the variables if, ii and Sud 



(see section [4.2.1 ). The logical function olsavemarked permits determining whether or not a 



given observing level is recorded into a compressed file. 

Miscellaneous routines. The library contains some other routines than may be useful in certain ap- 
plications, for example the pseudo-random number utilities raninit, urandom,urandomt, and 
grandom. 



The AIRES object library is not completely developed yet, so additional procedures will be surely 
included in future AIRES versions. 



Chapter 5 

The AIRES Runner System 



Production simulation tasks usually require large amounts of computer time to complete, and in such 
cases the user risks loosing all the simulation run if the system goes down before the task is finished. 
To avoid this inconvenient situation, the AIRES simulation system provides a special auto-saving 
mechanism that permits splitting the simulation job into small runs. In case of abnormal inteiTuption, 
the simulations can be restarted at the point they were when the last auto-saving was performed. 

As explained in chapter ^ (page 43), a simulation task may require several invocations of the 
simulation program if the auto-save mechanism is enabled. If this is done manually, the user must 
control the sequence of instructions needed to complete the simulations. To ease the management of 
such sequential series of processes, a set of scripts were developed with the capability of automatically 
launching the corresponding jobs. These scripts are part of the AIRES Runner System (ARS), designed 
as a set of interactive procedures to manage complex simulations tasks. 

The AIRES Runner System works only on UNIX platforms[], and provides tools for input file 
checking, sequential and concun^ent task processing, event logging, etc. This chapter is devoted to 
present some examples that will help the user to get familiar- with the Runner System. 

There are many parameters that modify the behavior of the AIRES Runner System. Most of them 
ai^e user-settable and their definition statements ai^e placed within the ARS initializing file .airesrc. In 
standard AIRES installations, this file is placed in the user's home directory. 



5.1 Checking input files 



In section |3.2.2| (page |44|), the IDL directives CheckOnly and Trace were used to instruct AIRES 
simulation programs to scan a given input file, report on its contents and stop without actually starting 
the simulations. 

The ARS command 

airescheck -t myfile.inp 



'There may be some incompatibilities when running ARS commands in clusters employing "afs" file systems. 
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will invoke Aires with the same input as displayed in page 45. The -t qualifier is placed to enable 
typing the input lines as long as they are scanned. 

There are additional qualifiers accepted by this command, for example: 

airescheck -tP -p AiresQ myfile.inp 

The -p qualifier overrides the default simulation program used to process the input file, and the P 
switch indicates that the output must be printed instead of being typed at the terminal. The print 
command to use can be set modifying the .airesrc initializing file. 



5.2 Managing simulation tasl<s 

Once the input file has been checked, the simulations can be started. The command 
airestask myfile 

will first check that file myfile.inp^ exists, and then will create an entry in the corresponding ARS 
spool. Finally, aireslaunch will be executed. 

The aireslaunch script will detect that there is a task pending completion and so will prompt the 
user to start the simulations. In case of positive answer, the simulation program will be started with 
the con^esponding input, and will be repeatedly invoked if necessary until the task is completed[]. All 
those operations are completely automatic, no further user intervention is normally required. 

If there are more than one task to be processed, they can be spooled at any moment after launching 
the first simulations. The command 

airestask my_other_f ile 

will make a new spool entry which will be queued after the first one. Execution of this task will start 
as soon as the previous one is finished. There is no limit in the number of tasks that can be queued in 
the ARS spools. 

At any moment during the simulations, it is possible to inspect the evolution of the spooled tasks 
by means of the ARS command airesstatus. 

In the preceding examples, the default simulation program (which normally is the Aires program) 
will be used. There are two alternatives to ovenide the default specification: (i) Modify the default 
program setting of the initialization file .airesrc. (ii) Use the -p qualifier of the airestask command: 

airestask -p AiresQ yet_another_f ile 

AiresQ is the name of a variable defined within the initialization file, which indicates the executable 
program that contains a link to the QGSJET hadronic package.^ 

^airestask first assumes a default extension .inp for the input file name, and as a second alternative, tries to find the file 
whose complete name is as specified in the input parameter. 

^The simulation program communicates with the script via a file that contain information about the status of the simu- 
lations. 

■*Use -p AiresS to explicitly specify the simulation program linked to the SIBYLL hadronic collision model. 
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5.2.1 Canceling tasks and/or stopping the simulations 

Every spooled task can be canceled by means of the command airesuntask, for example: 

airesuntask my_other_f ile 

will erase the second spooled task of the preceding section. If the airesuntask command is invoked 
with no parameters, then it will prompt the user to cancel each one of the spooled tasks. 

It is not recommendable to remove the spool entries corresponding to tasks that are currently 
running. In such cases it is better to first stop the simulation program, and wait until the AIRES 
Runner System shuts down. 

The simulation program can be stopped with the ARS command airesstop, which generally is 
invoked with no arguments. This script originates an ordered shutdown of the simulations, which 
includes an update of the internal dump file, and may take up to several minutes to effectively interrupt 
the simulations. The command airesstatus can be used to monitor the status of the system during this 
process. 

On the other hand, a currently running simulation can be immediately aborted by means of com- 
mand aireskill. In this case the corresponding processes are killed without any previous auto-saving 
operation. 

Stopped simulations can always be restarted using aireslaunch. 

5.2.2 Performing custom operations between processes 

Every time a process^ ends, the ARS checks for the existence of a executable script named After- 
Process (case sensitive!), first in the current working directory, and then -if not found- in the default 
directory of the user's account (HOME directory). If the file is found, it is executed. 

The complete command line used when invoking the AfterProcess macro is the following: 

AfterProcess spool tn msg rc trial totsh lastsh prog 

where 

spool is the spool identification. 
tn is the task name. 

msg is a message string coming from the simulation program. Normally it takes the values End- 
OfTask or EndOfRun, indicating if the current task was or not finished, respectively. Other 
values are also possible and correspond to abnormal situations. 

rc is a numeric parameter, taking the value 2 if the run has been stopped using an AIRES. STOP file 
(command airesstop). 

^See section ^ (page p^ ). 
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trial is a numeric variable counting the number of trials for the current run. Generally takes the value 
1, but in certain circumstances, for example when relaunching AIRES after a system crash, it 
can take larger values. 

totsh is the total number of showers for the current task. 

lastsh is the last completed shower. 

prog is the instruction used to invoke AIRES, which includes the full name of the simulation program 
used in the last run. 

This powerful ARS option makes it possible for the user to perform operations of almost every 
kind after ending the processes. Of course, a certain degree of expertise with UNIX systems may 
be required in certain cases. Typical examples of operations that can be done using this facility are: 
File movement after completion of tasks (for example to massive storage systems), alerts of any type 
about conditions of the system, like full disks, etc. 

On return, the AfterProcess script can communicate with the ARS via the exit code. If it is zero 
then processing will continue normally, otherwise the ARS will send a mail notifying the abnormal 
return code and then will stop. If it is necessary to restart the simulations, it can be done using the 
ARS command aireslaunch. 

The following shell script is a very simple example of an "after process" macro: 

# ! /bin/sh 
# 

if[ $3 = EndOfTask ] 

then 

# 

# This code will be executed only after ending a task. 
# 

mv ${2} . grdpcles /mysaf eplace 

f i 

exit 



Notice that no action will be taken up to the end of a task. Whenever this happens, the corresponding 
ground particle file is moved to another directory. The command exit ensures normal return code; 
exit n with n 7^ means an abnormal exit and in this case the simulations will be stopped. 

5.3 Concurrent tasks 

In many cases it is necessary to simultaneously process more than one task. Systems having more than 
one CPU and/or clusters of machines sharing the same file system, are examples of such situation. 
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The AIRES Runner System provides certain tools designed to work under such circumstances. 
The key idea is to define more than one spool, and assign one spool to each processing unit, either a 
CPU or a machine inside the cluster. 

In the preceding examples, the airestask command was invoked without spool specification. The 
default spool is used in case of missing specification, and that is what was actually done in those 
examples. 

In the standard configuration there are 9 predefined spools, named respectively "1", "2", . . . , etc. 
Spool "1" is the default spool]^. The command 

airestask -s 2 myfile 

will create a spool entry placed in spool "2". The user will be prompted to start the simulations if 
there is currently no activity related with that spool. The command 

airesstatus 2 

will report on the simulations that are running at spool "2". 

In the following interactive session, it is illustrated how to launch three simultaneous tasks (it 
is assumed that the machine possesses various CPU's which can be automatically assigned to the 
launched processes): 

cd directoryl 

aireslaunch -s 1 taskl 

cd directory2 
aireslaunch -s 2 task2 

cd directoryS 

aireslaunch -s 3 -p AiresQ task3 

It is most important that the working directories of different tasks be also different: ConcuiTcnt 
simulation programs running with the same working directory may generate conflicts when commu- 
nicating with the ARS scripts. This fact is stressed by means of the cd commands of the example, 
where directoryl, directoryZ and directory3 must be different directory specifications. 

Notice also that the third spooling command makes use of an alternative simulation program in 
order to perform a different kind of simulation. Alternative programs may also be necessary when 
running simulations on clusters sharing the same file system but made with non compatible platforms. 
In those cases it is necessary to have different executable modules for each platform. Once such 
modules are available, it is possible to change the default programs corresponding to the different 
spools by means of suitable modifications to the .airesrc initialization. 

The details about how to make the AIRES Runner System work in complex operating environ- 
ments are rather technical and go beyond the scope of this manual. Such a job requires normally a 
good degree of expertise on UNIX systems. 

*The ARS includes also the commands mkairesspool and rmairesspool which allow the user to respectively create and 
delete spool directories. 
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5.4 Some commands to manage dump file data 

Chapter ^ (page ^3]) explains in detail the operations needed to retrieve data stored within the internal 
dump file in either its binary or ASCII versions. Some of them are frequently used and generally 
involve very similar sequences of instructions. A typical example is to export one or more tables 
coiTcsponding to an already finished task. 

The ARS includes a shell script that can be helpful in those cases. Consider for example the 
command (under UNIX) 

airesexport mytask 1001 1205 to 1213 

Its action is to invoke the AIRES summary program with the following input 

Summary Off 
TaskName mytask 
ExportTable 1001 
ExportTables 1205 1213 
End 

generating text files for tables 1001, 1205, 1207, 1211 and 1213 (see appendix 

In some cases it may be necessary to specify other parameters, like in the following example 

airesexport -w idfdir -O LM -s mytask 2501 

This command will generate single shower tables (enabled by the -s qualifier) as well as average 
ones. The options LM correspond to dN / dlogiQ E distributions with energies expressed in MeV 
(see section [4. 1.2| ), and the string following the -w qualifier (idfdir) indicates the directory where the 
IDF and/or ADF files are located (The global directory accordingly with the definitions of section 



5.4.1 Converting IDF binary files to ADF portable format. 

ADF files were implemented for AIRES version 2.0.0, and to have them written by the simulation 
programs after a task is completed, it is necessary to explicitly enable them by means of the IDL 
directive ADFile. The (binary) IDF is always generated, regardless of the input settings and/or the 
version of AIRES used. 

Of course, the IDF stores all the data associated with both input parameters and output observ- 
ables, and is enough for any kind of analysis provided the user always works with compatible com- 
puters. But this may not be the case when a person or group is working at different locations. For 
such cases, a portable file format is needed and the ADF becomes essential to enable data analysis in 
non-compatible workstations. 

If the ADF was not generated during the simulations, or if the simulations were performed using 
a version of AIRES previous to version 2.0.0, it must be created manually. The current AIRES 
distribution includes an IDF to ADF converting program, whose default name is AiresIDF2ADF. 
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This program can be used directly. It is just necessary to invoke it (no arguments needed) and 
answer to the prompts that will be appearing. 

On the other hand, the ARS includes a special shell script that permits converting files without 
calling AiresIDF2ADF manually. Let us illustrate how to use this command with an example. Sup- 
pose in a certain place there are some IDF files that need to be converted to ADF format. The UNIX 
command 

idf2adf tasknamel taskname2 tasknameS 

will search for the files tasknamel.idf, taskname2.idf, etc., and will call AiresIDF2ADF as many 
times as necessary, to create the portable files tasknamel.adf, taskname2.adf, etc. Of course, the 
old IDF files will remain unchanged. 

This script will work well in most cases. However, there might be special situations where it is 
necessary to use AiresIDF2ADF manually, for example when the IDF file is renamed with a new 
name not ending with ".idf". 
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Appendix A 

Installing AIRES and maintaining 
existing installations 



As mentioned in section L3 (page every AIRES distribution is currently packed in a single com- 
pressed UNIX tar file. In this appendix it is assumed that the software distribution was successfully 
decompressed and tar expanded. 



A.1 Installing AIRES 2.2.0 

In UNIX platforms, the installing procedure is quite simple: Almost everything is done automatically. 
The key points to take into account are: 

(a) A Unix shell script doinstall is provided. This script will install the software automatically. 

(b) The file config contains all the customizable variables. You must edit it before invoking doin- 
stall 

(c) There will be two main directories: 

1. Installation root directory (hereinafter named Iroot), which is the directory where the 
distribution file was downloaded (that is, the directory containing the doinstall script). 

2. Aires root directory (hereinafter named Aroot), which is the highest level directory for 
the installed files. You will need to specify Aroot. For standard, personal installation, 
the default (creating a directory named aires in your home directory) will be OK. Notice 
that the Iroot and Aroot directories may or may not be the same directory (Do not worry 
about this: The installation program will manage every case properly.). 

(d) Your account must have access to a FORTRAN 77 compiler (normally, commands f77 or 
fort77), and in some cases to a C compiler (commands cc, gcc, etc.); and these compilers 
must be placed in one of the PATH directories (in other words, if you type at your terminal, say, 
f 77, the machine will take f 77 as a known command). If the compilers are not in the PATH 
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you will have to enter their absolute location manually in the config file (Our recommendation, 
however, is to ensure that the compilers are in the PATH. It is something not difficult to achieve. 
If you do not know how to proceed or what we are speaking about, then ask your local UNIX 
expert). 

(e) The simulation program uses scratch files for internal data paging. The scratch space needed 
for a run depends on the input parameters and the size of the internal particle stacks. For 
ultra-high-energy, hard-thinned showers (Primary energy greater than 10^^ eV, primary energy 
over thinning energy ratio greater than 10^.), and for a stack size of 5 MB (the default), a 
minimum of 15-20 MB scratch file space will be needed during the simulations. This figure 
can be more than 100 MB for very "heavy" simulations. If you want to reduce the scratch 
space requirements, then you will have to lower the stack size, modifying the corresponding 
parameter in file config. 

A.1 .1 Installation procedure step by step 

1. Ensure that you have write permission on both Iroot and Aroot directories, and in all their 
sub-directories. 

2. cd to Iroot, and edit the file config. Set all the variables accordingly with the guidelines therein 
placed and with your needs. It is mandatory to select one and only one platform. If none of the 
specified platforms match your machine, then you should try using "the most adequate one", 
continuing with the installation procedure and seeing what happens. Save the file and leave the 
edit session when finished. 

3. Enter the command 

doinstall 
if you are installing AIRES for the first time, or 
doinstall 1 

if you are upgrading your current installation (This is the case for those users that are already 
employing a previous version of AIRES. Note that you must not erase any existing installation 
of AIRES before completing the upgrade.). 

This procedure will install the software using the data you set in step 2. This may take some 
minutes to complete. A message will be typed at your terminal indicating whether the in- 
stallation was successful or not. If you get any error message(s), you should check all the 
requirements described previously, in particular points (d) and (1). Try also modifying the 
config file. 
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4. Type the command (case sensitive)[] 

Aires 

to see if the program is running and is in your search path. You should see typed at your 
terminal something like the following text[|: 

>>>> 

>>>> This is AIRES version V.V.V (dd/Mmm/yyyy ) 
>>>> (Compiled by 

>>>> USER: uuuuu, HOST: hhhhhhh, DATE: dd/Mmm/yyyy 
>>>> 

> dd/Mmm/yyyy hh:mm:ss. Reading data from standard input unit 

where V.V.V indicates the current version of AIRES (2.2.0) and goes together with the release 
date. Type x and press (ENTER) to leave the program. 

If step 3 ended successfully and you fail to run the program, it is likely that the AIRES bin 
directory is not in your environment search path (Unix environment variable PATH). In some 
systems you need to log out and log in again to make effective any PATH change. If you cannot 
place the AIRES bin directory into your account's PATH, then ask a Unix expert to do that for 
you. Once you are sure that the directory is in the search path, and if the problem still persists, 
check if the executable file Aires exists. If it does not exist that means that step 3 was not 
successfully completed. Do not continue with the next step until you succeed with this one. 

5. cd to your HOME directory and verify the presence of a file named .airesrc. 

Normally it is not necessary to change anything in this file, but the need may appear in the 
future, specially if you decide to use the UNIX scripts that are provided to help running AIRES 
(see chapter III). 

6. If you completed successfully these steps, the software should be properly installed. 

7. After successfully completing these steps you can delete the files corresponding to old ver- 
sions of AIRES. Such files are placed within the Aroot directory. For example, directory 1-2-0 
contains AIRES 1.2.0 files, etc. 

'The name Aires can be changed modifying adequately the config file. If this name was changed, then the user supplied 
name must be typed in place of the default one. 

^ You should also obtain a similar output if you invoke the AIRES/QGSJET simulation program AiresQ instead of Aires. 
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A.2 Recompiling tlie simulation programs 

In many cases it may be necessary to recompile the simulation programs after having successfully 
installed the AIRES system. Some examples of such situations are: 

• Some compilation parameters were not set accordingly with the user needs; or the required 
configuration is no more the one set up at the moment of installing the software. 

• It is necessary to install AIRES in different (not compatible) platforms sharing the same direc- 
tory tree. 

• It is necessary to create more than one executable program, each one compiled with different 
compilation parameters. As an example of this case, consider that the number and kind of 
records that are written in the compressed particle files can be controlled by means of compila- 
tion parameters (see section [4.2.1 ), and that it is required to have the executables for different 



file formats. 

The arguments recognized by the doinstall executable script allow the user to easily perform the 
different operation required in cases like the ones previously enumerated. 
The general syntax of doinstall is: 

doinstall ilev [ cfext ] 

ilev is an integer ranging from to 4 indicating the "level" of installation: 

Complete installation of the AIRES system. Necessary only when first installing AIRES. 

1 Upgrade of an existing installation, making the installed version the new current version. 

2 Recompiling. All the simulation programs and the summary program are compiled and linked. The 

AIRES object library is rebuilt. 

3 Relinking. New executables for all the simulation programs and the summary program are created 

using the existing object files. 

4 Rebuilding the library. The AIRES object library is rebuilt using the existing object files. 

cfext is an optional argument. It is a character string indicating that an alternative configuration file 
must be used to set the installation parameters. If cfext is no null, then the file config.c/<?jc^ is used 
instead of the default config file used when cfext is not specified. 

To perform different compilation/installation jobs, it might be useful to have several configuration 
files. For example, the config file is first copied to a new config.short file. Then config.short is 
edited changing the following parameters: (i) The format for both ground and longitudinal tracking 
compressed files is set to "short", (ii) The name of the executable program Aires is changed into 
Aires_sht. Finally the command 



doinstall 2 short 
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is executed. This will generate two new executable programs, namely, Aires_sht and Aires_shtQ 
which will be capable of producing compressed files with short format particle records. 



Appendix B 

IDL reference manual 



Both the main simulation programs Aires and AiresQ, and the summary program AiresSry use a 
common language to receive the user's instructions. This language is called Input Directive Language 
(IDL), and cuiTcntly consists of some 70 different instructions to set simulation parameters, control 
the output data, etc. In this section we list, alphabetically ordered, all AIRES 2.2.0 IDL directives. 

The IDL directives can be written using no special format, with one directive per line (there are 
no "continuation lines", but each line can contain up to 176 characters). The directives start with the 
directive name followed by the corresponding parameters. All the "words" that form a sentence must 
be separated by blanks and/or tab characters. 

All directives ai^e scanned until either an End directive or an end of file is found. Most directives 
can be placed in any order within the input stream. The Input directive permits inserting instructions 
placed in separate files letting the user to conveniently organize complex input data sets. Input 
directives can be nested. 

Dynamic (can be set every time the input file is scanned), static (can be set only at task initial- 
ization time) and hidder^ (associated with rarely changing parameters) directives are respectively 
marked as d, s, h. Names in typewriter or boldface font refer to keywords, while names in ital- 
ics refer to variable parameters. Underlined parts of keywords refers to shortest abbreviations: Not 
underlined characters are optional. Expressions between square brackets ([ expression ]) ai^e optional, 
while alternatives are written in the following way: { alt J \ alt_2 }. To specify angles, lengths, times, 
energies, atmospheric depths, magnetic fields, etc., it is required to give two fields separated by blank 
space: 

number unit 

number is a decimal number and unit is a character string representing the physical unit used in the 



specification. All the valid units are listed in table 3.1 (page 47). Additionally, time specifications 
may be of the form: [ number hr ] [ number min ] [ number sec ], where number represents a 
floating point number. 



'Hidden directives are connected to parameters that seldom need to be modified. They are not printed in the input data 
summary, unless were explicitly set or a full listing mode was enabled. Notice that this only affects output data printing: 
All other directive properties remain unchanged. 
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B.1 List of IDL directives. 

# 

Comment character. For every scanned input line, all characters placed after the comment 
character '#' are ignored. 

& 

Syntax: &label 

IDL label. Labels are used by directives Remark and Skip. The & must be the first non-blank 
character in the line, and all characters after label aie treated as a comment, label is a non null 
string which can contain any character excluding blanks and the comment character #. 

AddSite 

Syntax: AddSite name lat long height 

(d) Appending a new site to the AIRES site library, name is a string having no more than 16 
characters, and must be different to all the previously defined sites including the predefined 



entries listed in table (page Site names are case sensitive, lat and long are angle 
specifications defining respectively the geographic latitude and longitude of the site, lat (long) 
must be in the range [-90°, 90°] ([-180°, 180°]). height is a length specification defining the 
site's altitude above sea level. The directive Site permits to select already defined locations. 

AddSpecialParticle 

Syntax: AddSpec ialParticle pname module [parstring] 

(d) Adding a new definition to the list of special particles, pname is a string having no more 
that 16 characters that uniquely identifies the special particle being defined, module is the 
name of the executable module associated to the special particle. The file module must exist 
in the current "working directory" or in one of the directories that were specified with directive 
InputPath. Every time a new shower with "primary" pname starts, the module module will 
be executed by the main simulation program to generate a list of (standard) primary particles 



that will be the actual shower primaries. Section |3^ (page |66|) contains a detailed description 
about how to build and use such kind of modules, parstring is an optional parameter string 
(can contain embedded blanks) that is (portably) passed to the external module. 

ADFile 

Syntax: ADF ile [ { On | Off } ] 

Default: ADFile is equivalent to ADFile On 

ADFile Off is assumed in case of missing specification. 



(d) If ADFile On is specified, then an ASCII dump file will be generated upon task completion. 
The ASCII dump file (ADF) is a portable version of the internal dump file (IDF) that can be 
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transferred among different platforms. 

AirAvgZ/A 

Syntax: AirAvqZ/A number 
Default: AirAvgZ/A 0.5 

(s,h) Sets the value of the average ratio Z/A for air. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

AirRadLength 

Syntax: AirRadLength number 
Default: AirRadLength 37 . 1 

(s,h) Sets the value of the radiation length for air, expressed in g/cm^. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

AirZeff 

Syntax: AirZ eff number 
Default: AirZeff 7.3 

(s,h) Sets the value of the effective atomic number Z for air. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

Atmosphere 

Syntax: Atmosp here label 
Default: Atmosphere 1 

(s) Switches among different atmospheric models, label is an integer labelling the models avail- 
able. These models are currently two: (1) Linsley's standard atmosphere model. (2) Linsley's 
model for the South Pole. 

CheckOnly 

Syntax: Check Only [ { On | Off } ] 

Default: CheckOnly is equivalent to CheckOnly On 

CheckOnly Off is assumed in case of missing specification. 

(d) When CheckOnly is enabled, the simulation program reads and process all the input data 
normally, performs the internal consistency checks and then exits without starting the simula- 
tions. This directive is useful for input file debugging. 
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CommentCharacter 

Syntax: CommentChar acter { char \ nnn } 

Default: The default comment character is '#' 

(d) The plain text files produced with the ExportTables directive can have heading and trailing 
lines. All these lines start with a comment character in their first column. The default comment 
character ('#') is normally OK, but if the Export' ed files must be used as input of another 
program (a plotting utility, for example) which recognizes a different comment character, the 
CommentCharacter directive permits setting this mentioned character, char can be any single 
character (with no quotes). Alternatively, the comment character can be specified by means of 
its ASCII decimal code, expressed in the form of a three-figure number nnn (This permits using 
non-printable comment characters as well as resetting the comment character to '#'). 

Date 

Syntax: Date fpyear 

Date year month day 
Default: The current date at the moment of invoking the program. 

(s) This directive sets the date assumed for the simulations. The date is used at the moment of 
evaluating the geomagnetic field by means of the IGRF model (see sections [2.1.5| and 3.3.4 ). 



Setting the date may be necessary when performing simulations with the purpose of analyzing 
a certain air shower event reported by an experiment. The date can be specified either as three 
integers (year month day) or a floating point number with the format "year.part_of_the_year". 

DielectricSuppression 

Syntax: DielectricSupp ression [ { On | Off } ] 

Default: DielectricSuppression is equivalent to DielectricSuppression 
On 

DielectricSuppression On is assumed in case of missing specification. 
(s,h) Switch to include/exclude the dielectric suppression effect from the LPM algorithms [ p^ . 



23] for the case of electron or positron bremsstrahlung. The effect is enabled by default. 



Disabling it may lead to non realistic air shower simulations. If LPMEffect Off is in effect 



(see page |117D , then the dielectric suppression is always disabled. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

DumpFile 

Syntax: Dump F i 1 e 
Reserved for future use. 
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ElectronCutEnergy 

Syntax: ElectronCut Energy energy 
Default: ElectronCutEnergy 90 KeV 

(s) Minimum kinetic energy for electrons and positrons. Every electron having a kinetic en- 
ergy below this threshold is not taken into account in the simulation; positrons are forced to 
annihilation, energy must be greater than or equal to 90 keV. 

ElectronRoughCut 

Syntax: ElectronR oughCut energy 
Default: ElectronRoughCut 900 KeV 

(s) Electrons and positrons are not followed using detailed calculations when their energy is 
below the one specified by means of this directive. This means that several processes are not 
taken into account, for example Coulomb scattering, energy must be greater than or equal to 
45 keV. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

ELimsTables 

Syntax: ELimsT ables minenergy maxenergy 
Default: ELimsTables 10 MeV emax 

emax is the maximum between 10 TeV and 0.75 -^primary 

(s) This directive defines the energy interval to use in the energy distribution tables (his- 
tograms). Each energy distribution histogram consists of 40 logarithmic bins starting with 
minenergy (lower energy of bin 1) and ending with maxenergy (upper energy of bin 40). 

End 

Syntax: End 

(d) End of directive stream for the current input file. The file is no more scanned when this 
directive is found. If End is not present, the file is entirely scanned. 

Exit 

Syntax: Exit 

X 



(d) The program is stopped without taking any further action. This directive is useful to end 
an interactive session. 
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ExportPerShower 

Syntax: ExportP erShower [ { On | Off } ] 

Default: ExportPerShower is equivalent to ExportPerShower On 

ExportPerShower Off is assumed in case of missing specification. 

(d) This directive affects only those tasks simulated with the PerShowerData Full option (see 



page 120). If ExportPerShower On is specified, then a set of plain text files (one file per 
simulated shower) will be written for all the tables selected for exporting (see directive Ex- 
portTables). Each one of these "single shower" tables contains the values adopted by the 
corresponding observable in the respective shower. The normal table containing the average 
over showers is also exported, and is not affected by this directive. 

ExportTables 

Syntax: Export Tables mincode [maxcode ] [Options optstring] 
Export Tables Clear 

Default: No tables are exported by default. 

(d) Tables whose codes range from mincode to maxcode are selected for exporting as plain text 
files. If maxcode is not specified, it is taken equal to mincode. The table codes are integers. A 
complete list of available tables (more than 180) is placed in appendix B, or can be obtained 
with directives Help tables and/or Tablelndex. The Clear option permits clearing the list 
of exported tables, thus oveniding all the previous ExportTables directives, opstring is a 
string of characters to set available options: s (h) suppress (include) file header; x (X) include 
"border" bins as comments (within the data); U do not include "border" bins; r (d) normal 
(density) lateral distributions; L (1) distributions normalized as d/dlog^o (d/dln); r (a) express 
atmospheric depth as vertical (slant) depths; K, M, G, T, P, E, express energies in keV, MeV, 
. . . , EeV. The default options are: hxrG. 

ExtCoUModel 

Syntax: ExtCollM odel [ { On | Off } ] 

Default: ExtCollModel is equivalent to ExtCollModel On 

ExtCollModel On is assumed in case of missing specification. 

(s) Switch to enable/disable the external hadronic interactions model: SIBYLL [||] in the case 
of the Aires program or QGSJET for the AiresQ main simulation program. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 
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FileDirectory 

Syntax: FileDir ectory dopt directory 

Default: The output and scratch directories default to the current (working) directory. The 
global and export directories default to the current value of the output directory. 

(d) This directive sets the output file directories^ dopt is a character string that can take any one 
of the following values: All, Output, Global, Export, or Scratch. These alternatives 



permit setting all the AIRES directories defined in section [3.3.2| (page The option All can 
be used to simultaneously set the "output" (compressed file), "global" and "export" directories. 
directory is a character string not longer than 94 characters that must be recognized by the 
operating system as a valid directory. 

FirstShowerNumber 

Syntax: FirstSh owerNumber fshowerno 
Default: FirstShowerNumber 1 

(s) A positive integer in the range [1, 759375] indicating the number to be assigned to the first 
simulated shower. The shower number is used in tables 5000 to 5513, and in the "beginning of 
shower" and "end of shower" compressed file records (for details see chapter 0). 

Forcelnit 

Syntax: Forcelnit [ { On | Off } ] 

Default: Forcelnit is equivalent to Forcelnit On 

Forcelnit Off is assumed in case of missing specification. 

(d) If Forcelnit is enabled, then a new task is started at the beginning of every process. If 
the corresponding IDF file exists, then the task version is increased until an unused version is 
found. This directive is useful for debugging purposes. 

ForceModelName 

Syntax: ForceModelName modsel 

Default: No model name check is performed when this directive is not used. 

(s) This directive allows the user to force that a given input data set will be processed with the 
simulation program linked with the external collision package specified with modsel. Currently 
modsel can be one of (case dependent!) SIBYLL or QGSJET. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 



^The old (AIRES 1.4.2 and older) syntax is no longer supported. 
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GammaCutEnergy 

Syntax: GammaCut Energy energy 
Default: GammaCutEnergy 90 KeV 

(s) Minimum energy for gammas. Every gamma ray having an energy below this thi^eshold is 
not taken into account in the simulation, energy must be greater than or equal to 90 keV. 

GammaRoughCut 

Syntax: GammaR oughCut energy 
Default: GammaRoughCut 750 KeV 

(s) Gamma rays are not followed using detailed calculations when their energy is below the 
one specified by means of this directive. This means that several processes ai^e not taken into 
account, for example pair production, energy must be greater than or equal to 45 keV. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

GeomagneticField 

Syntax: Geomag neticField [ { On | Off } ] 

Geomag neticField stg [ inc [ dec ] ] [ Fluctuations flue ] 
Geomag neticField [On] Fluctuations flue 
Default: GeomagneticField Off when there is no Site specification; 
GeomagneticField On otherwise. 

(s) Setting the geomagnetic field manually and/or enabling magnetic fluctuations, stg must be 
a valid magnetic field strength specification, and inc and dec are angle specifications. Such 
fields correspond respectively to the geomagnetic field strength, F, and to the inclination, I, and 



declination, D, angles defined in section [2. 1.5| (page [18|). When one or more of such parameters 



are entered by means of the GeomagneticField directive, they override the respective values 



that are calculated automatically using the IGRF model [g], as explained in section [3.3.4| (page 
|6T| ). The fluctuation specification flue adopts three different formats: (i) Absolute: In this case 
flue represents a (positive) magnetic field strength, (ii) Relative: flue adopts the foTmat number 
Relative, and refers to the ratio between the actual fluctuation strength and the average value of 
the magnetic field, (iii) In percent: flue adopts the format number %_. number corresponds to 
a relative specification multiplied by 100. The effect of magnetic field fluctuations is explained 
in section |3.3.4] (page |6T| ). 
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GroundAltitude 

Syntax: GroundA ltitude altdepth 
GroundP epth altdepth 

Default: The altitude of the site currently in effect. 

(s) Ground level altitude, altdepth can be either a length specification (ranging from to 112 
km) or an atmospheric depth specification (ranging from to 1033 glcw?). 

HadronCutEnergy 

Syntax: HadronCut Energy energy 
Default: HadronCutEnergy 1 . 1 GeV 

(s,h) Minimum total energy for secondaries produced in inelastic collision process. All secon- 
daiies with energies lower than this threshold are not tracked, energy must be greater or equal 
than the neutron rest mass. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

Heavy Mineko 

Syntax: HeavyMineko energy 
Default: HeavyMineko 10 MeV 

(s,h) Energy parameter for heavy particle knock-on electron production, energy must be greater 
than or equal to 100 keV. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

Help 

Syntax: Help [ { * | table s | site s } ] 
help [ { * I table s | sites } ] 
? [ { * I tables I sites } ] 

(d) The action of the Help directive is to type a brief summary of IDL directives, output data 
tables (histograms) or sites defined in the AIRES site library. Help * gives a full IDL directive 
list, including all "hidden" directives. The ? form is equivalent to the combined action of Help 
and Prompt On 

Inj ection Altitude 

Syntax: Inject ionAltitude altdepth 

InjectionP epth altdepth 
Default: InjectionAltitude 100 km 



(s) Primary injection altitude, altdepth can be either a length specification (ranging from to 
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1 12 km) or an atmospheric depth specification (ranging from to 1033 g/cm^). 

Input 

Syntax: Inp ut file 

(d) File file is inserted in the input data stream. Input directives can be nested. The search path 



for locating input files include the "working directory" (see section [3.3.2| ) and all the directories 
that were specified with directive InputPath. 

InputListing 

Syntax: InputLis ting [ { Brief | Full } ] 

Default: InputListing is equivalent to InputListing Brief 

InputListing Brief is assumed in case of missing specification. 

(d) Data related to hidden input directives are not printed in the output summary file unless the 
corresponding variables were explicitly set or InputListing Full was specified. 

InputPath 

Syntax: InputP ath r Append 1 \dirl\:dir2\:...] 1 1 

Default: No path besides the "working directory" is set by default. 

(d) Modifying the directory search path for the files included with the Input directive and/or 
executable modules referred by AddSpecialParticle instructions. This directive can be used 
multiple times if required. Different search directories can be specified in a single invocation 
separating them with colons (:) with no embedded blanks. The keyword Append indicates 
that the specified directory(ies) must be appended to the ones already inserted. If InputPath is 
invoked with no arguments, then the seaixh path is cleai^ed. 

LaTeX 

Syntax: LaTeX [ { On | Off } ] 

Default: LaTeX is equivalent to LaTeX On 

LaTeX Off is assumed in case of missing specification. 

(d) If LaTeX On is specified, then the output summary file is written using the I^TgX word 
processor format. Otherwise it is written as a plain text file. When this option is enabled, a TgX 
file taskname.tex is created simultaneously with the summary file. 

LPMEffect 

Syntax: LPME ffect [ { On | Off } ] 

Default: LPMEffect is equivalent to LPMEffect On 

LPMEffect On is assumed in case of missing specification. 



(s,h) Switch to include/exclude the Landau-Pomeranchuk-Migdal effect [^, 17] from the elec- 
tron-positron and gamma propagating algorithms. The effect is enabled by default. Disabling 
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it may lead to non realistic air shower simulations. If LPMEffect Off is in effect, then the 



dielectric suppression is also disabled (see page 111) 



This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

MaxCpuTimePerRun 

Syntax: MaxCpu T imeP e r Run { time \ Inf inite } 
Default: MaxCpuTimePerRun Infinite 

(d) This directive sets the maximum CPU time for individual runs, being a run the processing 
chunk that goes between two consecutive updates of the internal dump file. This parameter 
does not impose any restriction on the CPU time available for the simulation of a single shower 
(or a group of them), which is always infinite, time is any valid time specification. See also 
directives RunsPerProcess and ShowersPerRun. 

MesonCutEnergy 

Syntax: MesonCut Energy energy 
Default: MesonCutEnergy 60 MeV 

(s) Minimum kinetic energy for mesons (pions, kaons, etc.). Every meson having a kinetic 
energy below this threshold is not taken into account in the simulation; unstable particles are 
forced to decays, energy must be greater than or equal to 500 keV. 

MFPHadronic 

Syntax: MFP Hadronic mfpsel 

Default: MFPHadronic SIBYLL (MFPHadronic QGS JET) for program Aires 
(AiresQ). 

(s) Directive to select among different sets of mean free paths parameterizations^. mfpsel is a 
character string that can take any one of the following values: Standa rd, SIBYLL QGS JET , 
or Bartol . Each alternative correspond to different parameterizations for the mean free path 
of hadron-air and nucleus-air collisions. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

MFPThreshold 

Syntax: MFPThre shold energy 
Default: MFPThreshold 50 GeV 

(s,h) Threshold energy for the currently effective mean free pathsQ All hadronic collisions 



^The obsolete AIRES 1.4.2 directive BartolMFP is no longer supported, it must be replaced by MFPHadronic Bartol. 
■*The obsolete AIRES 1.4.2 directive BartolThreshold is no longer supported, it must be replaced by directive MF- 
PThreshold. 
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with energy greater than or equal to this threshold will be processed using the current mfp 
parameterization (that can be set using directive MFPHadronic); otherwise standard MFP's 
will be used, energy must be greater than or equal to 200 MeV. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

MinExtCoUEnergy 

Syntax: MinExtCoUE nergy energy 
Default: MinExtCoUEnergy 200 GeV 

(s,h) Threshold energy for invoking the external hadronic collision routine (if enabled), energy 
must be greater than or equal to 25 GeV. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

MuonCutEnergy 

Syntax: MuonCut Energy energy 
Default: MuonCutEnergy 10 MeV 

(s) Minimum kinetic energy for muons. Every muon having a kinetic energy below this thresh- 
old is not taken into account in the simulation; it is forced to a decay, energy must be greater 
than or equal to 500 keV. 

NuclCoUisions 

Syntax: NuclCoU isions [ { On | Off } ] 

Default: NuclCoUisions is equivalent to NuclCoUisions On 

NuclCoUisions On is assumed in case of missing specification. 

(s,h) Switch to include/exclude the hadronic inelastic collisions with air nucleus from the heavy 
particles propagating algorithms. The collisions ai^e enabled by default. Disabling them may 
lead to non realistic air shower simulations. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

NuclCutEnergy 

Syntax: NuclCutEnergy energy 
Default: NuclCutEnergy 120 MeV 

(s) Minimum kinetic energy for nucleons and nuclei. Every such particle having a kinetic 
energy below this threshold is not taken into account in the simulation, energy must be greater 
than or equal to 500 keV. 
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ObservingLevels 

Syntax: Observing Levels nofol [ altdepthl altdepthl ] 
Default: ObservingLevels 19 

(s) This directive defines the number and position of the observing levels used for longitudinal 



development recording (see page 25) . altdepthl and altdepthl we. altitude (or atmospheric 
depth) specifications that define the positions of the first and last observing levels, nofol is an 
integer that sets the number of observing levels. It must lie in the range [4, 510]. The observing 
levels are equally spaced in atmospheric depth units. The first (last) level corresponds to the 
highest (lowest) altitude. 

If altdepthl and altdepthl are not specified, then the observing levels are placed between the 
injection and ground planes, but spacing them differently (see section p. 3. 3 ): The injection 



level corresponds to observing level "0" while the ground level corresponds to observing level 
"nofol + 1". For example, if the injection (ground) level is placed at (1000) glcw?, the 
directive ObservingLevels 19 will set 19 observing levels placed at depths 50, 100, 150, . . . , 
950 g/cm2. 

OutputListing 

Syntax: OutputLis ting [ { Brief | Full } ] 

Default: OutputListing is equivalent to OutputListing Brief 

OutputListing Brief is assumed in case of missing specification. 

(d) Hidden output data items are not printed in the output summary file unless OutputListing 
Full is specified. 

PerShowerData 

Syntax: PerShower Data option 

Default: PerShowerData is equivalent to PerShowerData Full 

PerShowerData Brief is assumed in case of missing specification. 

(s) Directive to control the amount of individual shower data to be stored after each shower is 
completed, option is a character string that can take any one of the following values: None, 
Brief or Full. When None is specified, no individual shower data is saved. The Brief level 
implies saving global parameters such as the depth of shower maximum Xmax> for example; 



and the Full level is the Brief level plus all the single shower tables (see page |113| ). 



PhotoNuclear 

Syntax: PhotoNuc lear [ { On | Off } ] 

Default: PhotoNuclear is equivalent to PhotoNuclear On 

PhotoNuclear On is assumed in case of missing specification. 



(s,h) Switch to include/exclude the inelastic collisions gamma-air nucleus (photonuclear re- 
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actions) from the gamma ray propagating algorithms. The collisions are enabled by default. 
Disabling them may lead to non realistic air shower simulations. 

This directive belongs to the model-dependent IDL instruction set and may be changed or not 
implemented in future versions of AIRES. 

PrimaryAzimAngle 

Syntax: PrimaryA zimAncrle minang [ maxang ] [ { Magnetic | Geographic } ] 
Default: PrimaryAzimAngle deg Magnetic if the zenith angle is fixed; 

PrimaryAzimAngle deg 360 deg Magnetic otherwise 

(see PrimaryZenAngle). 

(s) Primary azimuth angle. The angle for each shower is selected with uniform probability 
distribution in the interval [minang, maxang] . If the angle maxang is not specified, it is taken 
equal to minang (fixed azimuth angle). The Geographic keyword indicates that the specified 
azimuth is measured with respect to the geographic north, positive for eastwards directions; in 



this case the azimuth angle used by AIRES is obtained applying equation (3.8). If no keyword 
or the Magnetic keyword is specified, then the origin for the azimuths is the magnetic north, 
and the given angles ai^e interpreted accordingly with the orientation of the AIRES coordinate 
system defined in section [2.1. 1| (page p^ ). 

PrimaryEnergy 

Syntax: PrimaryE nergy minener [ maxener [ gamma ] ] 

Default: None. This directive is always required. 

(s) Energy of primary. If only minener is specified then all primaries have a fixed energy equal 
to this parameter. Otherwise the energy will be sampled from the interval [-Emin, -^max] = 



[minener, maxener] with the probability distribution of equation ( pJ| ) with exponent 7 option- 
ally specified by gamma. 

The primary energy must be larger than 10 GeV and less than 10^^ GeV (10^^ eV). There are 
no restrictions on 7. If not specified it is set to 1.7. 

PrimaryParticle 

Syntax: Primary Particle particle [ weight ] 

Default: None. This directive is always required. 

(s) Primary particle specification, particle is the particle name. Proton, Iron, Fe"56, etc. are 
valid particle names. Special particle names defined by means of directive AddSpecialParticle 
can also be used with this instruction. If more than one PrimaryParticle directive appear 
within the input instructions, then the primary particles will be selected at random among the 
different specified particle kinds, with probabilities proportional to the weights specified in the 
corresponding weight fields. If weight is not specified, then the particle weight is taken as 1. 



122 



Appendix B. IDL reference manual 



PrimaryZenAngle 

Syntax: PrimaryZ enAngle minang [ maxang [ { S | SC | CS } ] ] 
Default: PrimaryZenAngle deg 

(s) Primary zenith angle, Q. If only minang is specified, then the zenith angle is fixed and equal 
to this value, and the default for the azimuth angle will be 0. Otherwise the zenith angle for each 
shower is selected randomly within the interval [minang, maxang], with the sine probability 



distribution of equation (3.4), which is proportional to sin (default or S specification), or the 
sine-cosine probability distribution of equation ( |3.6| ), which is proportional to sin cos © (SC 
or CS specifications). In this case the default for the azimuth angle is PrimaryAzimAngle 
deg 360 deg. Both minang and maxang must belong to the interval [0°, 90°). 

PrintTables 

Syntax: Print Tables mincode [ maxcode ] [ Options optstring ] 
Print Tables Clear 

Default: No tables are printed by default. 

(d) Tables whose codes range from mincode to maxcode are selected for being displayed in the 
summary output file. If maxcode is not specified, it is taken equal to mincode. The table codes 
are integers. A complete list of available tables (more than 1 80) is placed in appendix ^ (page 



128), or can be obtained with directives Help tables and/or Tablelndex. The Clear option per- 
mits clearing the list of printed tables, thus ovemding all the previous PrintTables directives. 
opstring is a string of characters to set available options: n suppress plotting minimum (<) and 
maximum (>) characters; m include minimum and maximum plots in the tables; M do not in- 
sert character plots, make a completely numerical table instead; S (R) use standard deviations 
(RMS errors of the means) to plot error bars; r (d) normal (density) lateral distributions; L (1) 
distributions normahzed as d/dlogiQ (d/dln). The default options are: nSr. 

Prompt 

Syntax: Promp t [ { On | Off } ] 

Default: Prompt is equivalent to Prompt On 

Prompt Off is assumed in case of missing specification. 

(d) Turns prompting on/off. This directive is meaningful only in interactive sessions. 

PropagatePrimary 

Syntax: PropagateP rimary [ { On | Off } ] 

Default: PropagatePrimary is equivalent to PropagatePrimary On 

PropagatePrimary On is assumed in case of missing specification. 



(s,h) This directive controls the initial propagation of the primary. If the On option is selected 
(the default), then the primary is normally advanced before the first interaction takes place, and 
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therefore the first interaction altitude will be variable. Otherwise the first interaction will be 
forced to occur at the injection altitude. 



This directive is ignored for showers initiated by special primaries (see section 3.5). 



RandomSeed 

Syntax: RandomS eed seed 

RandomS eed Get From idfile 
Default: RandomSeed . 

(s) This directive sets the random number generator seed, seed is a real number. If it be- 
longs to the interval (0, 1) then the seed is effectively taken as the given number. Otherwise 
it is evaluated internally (using the system clock). The alternative syntax with the keyword 
GetFrom allows extracting the random generator seed from an already existing internal dump 
file.| This is most useful to reproducing a previous simulation repeating the original random 
number simulator configuration. 

RecordObsLevels 

Syntax: RecordOb sLevels [ Not ] [ levl [ lev2 [ step ] ] ] 

RecordOb sLevels [ Not ] { All | All /step \ None } 
Default: RecordObsLevels All 

(s) Directive to mark a certain subset of the defined observing levels for inclusion (or exclusion) 
in the set of levels that are included in the longitudinal tracking compressed particle file. The 
integer variables levl levl and step are the arguments of a FORTRAN do loop which starts at 
levl, ends at levl advancing in steps of step. The keyword Not indicates that the corresponding 
levels must be excluded for being recorded in the file. If levl and/or step are not indicated they 
default to levl and 1 respectively. RecordObsLevels AWIstep is a short form for RecordOb- 
sLevels 1 No step, where No is the number of defined observing levels. RecordObsLevels All 
is equivalent to RecordObsLevels All/1 while RecordObsLevels None can be used in place 
of RecordObsLevels Not All. This directive can be repeatedly used within an input instruction 



stream to mark or unmark arbitrary subsets of observing levels, as explained in page |87 



Remark 

Syntax: Rem ark string 
Rem ark Stlabel 

First line of remarks. 

Last line of remarks. 
&label 



(s) Remarks directive. Each time this directive appears in the input data stream, the correspond- 
^This is not supported for IDF files generates witli AIRES versions previous to version 2.0.0. 
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ing remark string(s) are appended to the remarks text. All the entered remarks will be printed 
in the log and summary files, and stored in different output data files. There is no limit in the 
number of remark lines, but every line cannot be longer than 75 characters. 

ResamplingRatio 

Syntax: Resamp lingRatio rsratio 
Default: ResamplingRatio 10 



(s) This directive sets the variable Sj, used in the resampling algorithm defined in section 38 



(page 84). rsratio is a real number that must be greater or equal than 1. 



RLimsFile 

Syntax: RLimsF ile filext rmin rmax 
Default: RLimsFile anyjile 250 m 12 km 

(s) This directive defines the lateral limits for the compressed data file whose extension]^ is 
filext. For the ground particle file, rmin and rmax define, together with the resampling ratio 
that is controlled by the IDL instruction ResamplingRatio the radial limits of the zone where 



the particles are going to be saved (see page 84). In the case of longitudinal tracking particle 



files, those parameters define the inclusion zone at ground level. At an arbitrary altitude, the 



particles ai^e included accordingly with the rules explained in section 4.2.1 (page 78) 



RLimsTables 

Syntax: RLimsT ables rmin rmax 
Default: RLimsTables 50 m 2 km 

(s) This directive defines the radial interval to use in the lateral distribution tables (histograms). 
Each lateral distribution histogram consists of 40 logarithmic bins starting with rmin (lower 
radius of bin 1) and ending withr/najc (upper radius of bin 40). 

RunsPerProcess 

Syntax: RunsPerP rocess { number \ Inf inite } 
Default: RunsPerProcess Infinite 

(d) Number of runs within a process (see also MaxCpuTimePerRun and SiiowersPerRun). 
SavelnFile 

Syntax: Save lnFile filext particlel [particle2] ... 
Default: SavelnFile grdpcles All 
SavelnFile Igtpcles None 

(s) This directive allows to control the particles being saved in the compressed file whose exten- 
sion is filext (see directive RLimsFile). particlel, particlel, . . . , are valid particle or particle 



*The extension of a file is what goes after the dot in the file name, like in fname.extension for instance. 
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group names. This directive, together with SaveNotlnFile are useful to save output file space 
in certain circumstances. 

SaveNotlnFile 

Syntax: SaveNot lnFile filext particle 1 {particle! ] ... 

(s) The syntax of this directive is similar to SavelnFile, and its meaning is opposite (SavelnFile 
filext None is equivalent to SaveNotlnFile filext All). 

SeparateShowers 

Syntax: SeparateS howers { Off | number } 
Default: SeparateShowers Off 

(s) In a task involving more than one shower, the compressed output files can be split into 
several pieces each one storing the data corresponding to number showers. In particular, Sepa- 
rateShowers 1 generates one compressed file per shower while SeparateShowers Off disables 
file splitting. 

SetTimeAtlnj ection 

Syntax: SetTimeAtlnj ection [ { On | Off } ] 

Default: SetTimeAtIn jection is equivalent to SetTimeAtlnjection On 

SetTimeAtIn jection On is assumed in case of missing specification. 

(s,h) Directive to set whether the time count for each shower is started at the moment of inject- 
ing the primary particle (On) or at its first interaction (Off). 



This directive is ignored for showers initiated by special primaries (see section 3.5). 



ShowersPerRun 

Syntax: ShowersP erRun { number \ Inf inite } 
Default: ShowersPerRun Infinite 

(d) Maximum number of showers in a run (see also MaxCpuTimePerRun and RunsPerPro- 
cess). Notice that this parameter is related with the computer environment only and does not 
affect the total number of showers that define a task (see TotalShowers). 



Site 



Syntax: Site name 
Default: Site SiteOO 

(s) The Site directive specify the geographical location that define the environment (latitude, 
longitude and altitude) where the simulations take place, name is a string identifying the se- 
lected site. It must either be one of the predefined sites of the AIRES site library, listed in table 



3.2| (page |6^), or have been previously defined by means of the AddSite directive. 
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Skip 

Syntax: Skip &label 

(d) Instruction to skip part of an input data stream. All directives placed after the Skip statement 
and before &label are skipped. Notice that this is not a "go to" statement: It is only possible to 
skip forwards, never backwards. 

SpecialParticLog 

Syntax: SpecialParticL ocr Ivl 

Default: SpecialParticLog is equivalent to SpecialParticLog 1 

SpecialParticLog is assumed in case of missing specification. 

(d) Controlling the amount of data related with special primary particles to be saved in the 
corresponding log file. Ivl is an integer parameter that can take the following values: 

No information written in the log file. 

1 Messages before and after invoking the external module. 

2 Level 1 plus detailed list of vahd primaries. 

Stacklnformation 

Syntax: Stackl nformation [ { On | Off } ] 

Default: Stacklnformation is equivalent to Stacklnformation On 

Stacklnformation Off is assumed in case of missing specification. 

(d) Directive to instruct AIRES to print detailed stack usage information in the summary output 
file. 

Summary 

Syntax: Summ ary [ { On | Off } ] 

Default: Summary is equivalent to Summary On 

Summary On is assumed in case of missing specification. 

(d) Directive to enable or disable the output summary. 

Tablelndex 

Syntax: Tablel ndex [ { On | Off } ] 

Default: Tablelndex is equivalent to Tablelndex On 

Tablelndex Off is assumed in case of missing specification. 



(d) Directive to instruct AIRES to print a table index in the summary output file. 
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TaskName 

Syntax: Task Name [ Append ] taskname [ taskversion ] 
Default: TaskName GIVE_MEJ^_NAME J>LEASE 

(d) Task name assignment, taskname is a character string which identifies the current task. If 
its length is greater than 64 characters, it will be truncated to the first 64 chai^acters. taskversion 
is an optional integer between (default) and 999. If taskversion is not zero, the effective task 
name is taskname Jaskversion . If the keyword Append is used, then taskname is appended to 
the existing task name string. The task name is used to set the file names of all output files. 

ThinningEnergy 

Syntax: Thin ningEnergy { energy \ number Relative } 
Default: ThinningEnergy 1 . Oe-4 Relative 

(s) Thinning energy. It can be expressed either as an absolute energy or as a real (positive) 
number with the keyword Relative (In this case the thinning energy is the primary energy 
times the specified number). 

Thinning WFactor 

Syntax: ThinningWF actor number 
Default: ThinningWFactor 1.0e20 

(s,h) Thinning weight factor. This instruction permits setting the weight factor Wf of equation 
( 2.23 ). With the default setting Wf = 10^^ , the weight limiting mechanism described in section 



2.3. 2| (page ^ is completely disabled. 



TotalShowers 

Syntax: TotalSh owers nof showers 
Default: None. This directive is always required. 

(d) Total number of showers, no/showers is a positive integer in the range [1, 759375] defin- 
ing the number of showers to be simulated in the cuiTcnt task. Notice that this is a dynamic 
parameter, that is, it can be modified (either enlarged or reduced) during the simulations. 

Trace 

Syntax: Trace [ { On | Off } ] 

Default: Trace is equivalent to Trace On 

Trace Off is assumed in case of missing specification. 

(d) Directive to enable or disable input data tracing. If enabled (On) then trace information 
about the directives being processed by the IDL parser is written into the standard output chan- 
nel. This directive is useful to debug IDL input data sets. 



Appendix C 

Output data table index 



We list here all the tables defined in AIRES 2.2.0. These tables can be processed using directives 
PrintTables and/or ExportTables (see chapter ^). 







Table name 




1 


1001 


Longitudinal development 


Gamma rays. 


2 


1005 


Longitudinal development 


Electrons. 


3 


1006 


Longitudinal development 


Positrons. 


4 


1007 


Longitudinal development 


Muons (+). 


5 


1008 


Longitudinal development 


Muons (-). 


6 


1011 


Longitudinal development 


Pions (+). 


7 


1012 


Longitudinal development 


Pions (— ). 


8 


1013 


Longitudinal development 


Kaons (+). 


9 


1014 


Longitudinal development 


Kaons (— ). 


10 


1021 


Longitudinal development 


Neutrons. 


11 


1022 


Longitudinal development 


Protons. 


12 


1023 


Longitudinal development 


Antiprotons. 


13 


1041 


Longitudinal development 


Nuclei. 


14 


1091 


Longitudinal development 


Other charged pcles. 


15 


1092 


Longitudinal development 


Other neutral pcles. 


16 


1205 


Longitudinal development 


e+ and e— 


17 


1207 


Longitudinal development 


mu+ and mu— 


18 


1211 


Longitudinal development 


pi+ and pi— 


19 


1213 


Longitudinal development 


K+ and K- 


20 


1291 


Longitudinal development 


All charged particles. 


21 


1292 


Longitudinal development 


All neutral particles. 


22 


1293 


Longitudinal development 


All particles. 


23 


1301 


Unweighted longit. development: Gamma rays. 


24 


1305 


Unweighted longit. development: Electrons. 


25 


1306 


Unweighted longit. development: Positrons. 
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Code 


ZD 




Z / 




Zo 


loll 


oo 

zy 


lolZ 


JU 


1 11 1 
lolo 


■ti 1 
JL 


1 11 /I 
1j14 


oo 


1 1ll 
IjZl 




1 1^^ 
loZZ 


34 


1 1^1 
IJZO 


3j 


1 1/1 1 

1j41 






37 


1392 


38 


1405 


39 


1407 


40 


1411 


41 


1413 


42 


1491 


43 


1492 


44 


1493 


/I c 
45 


1 CA1 
ISUl 


4o 


1 CAC 


4/ 




4b 


1 CAT 


4y 


1 CAQ 


jU 


1 CI 1 

ISll 


C 1 

jl 


1 CI ^ 

ISlZ 


JZ 


1 CI 1 
l3lj 


j3 


1 CI /I 

I3l4 


j4 


1 c^i 
ISZl 


cc 

JJ 


1 C^'> 

13ZZ 


CA 
JD 


1 01 
13ZJ 


5 / 


1 Cyl 1 
1541 


58 


1591 


59 


1592 


60 


1705 


61 


1707 


62 


1711 


63 


1713 


64 


1791 


65 


1792 


66 


1793 



Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 
Unweighted longit. development: 

Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 
Longitudinal development 



Muons (+). 
Muons (-). 
Pions (+). 
Pions (— ). 
Kaons (+). 
Kaons (— ). 
Neutrons. 
Protons. 
Antiprotons. 
Nuclei. 

Other charged pcles. 
Other neutral pcles. 
e+ and e— 
mu+ and mu— 
pi+ and pi— 
K+ and K- 
All charged particles. 
All neutral particles. 
All particles. 

Energy of gamma rays. 
Energy of electrons. 
Energy of positrons. 
Energy of muons (+). 
Energy of muons (— ). 
Energy of pions (+). 
Energy of pions (— ). 
Energy of kaons (+). 
Energy of kaons (— ). 
Energy of neutrons. 
Energy of protons. 
Energy of antiprotons. 
Energy of nuclei. 
Energy of other charged particles. 
Energy of other neutral particles. 
Energy of e+ and e— 
Energy of mu+ and mu— 
Energy of pi+ and pi- 
Energy of K+ and K— 
Energy of all charged particles. 
Energy of all neutral particles. 
Energy of all particles. 
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Code 


Table name 


0/ 


ZUUI 


Lateral distribution 


Do 


ZUU3 


Lateral distribution 


oy 


zUUo 


Lateral distribution 




ZUU/ 


Lateral distribution 


/I 




Lateral distribution 


TO 


ZUll 


Lateral distribution 


li 


2U12 


Lateral distribution 






Lateral distribution 


/j 


ZU14 


Lateral distribution 


lb 




Lateral distribution 


in 
1 1 


zuzz 


Lateral distribution 


la 


ZUZo 


Lateral distribution 


ly 


ZU41 


Lateral distribution 


\J\J 


2091 


T atpfal Hi Qtnhi ition 


81 


2092 


Lateral distribution 


82 


2205 


Lateral distribution 


83 


2207 


Lateral distribution 


84 


2211 


Lateral distribution 


85 


2213 


Lateral distribution 


86 


2291 


Lateral distribution 


87 


2292 


Lateral distribution 


88 


2293 


Lateral distribution 


by 


ZoUl 


Unweighted lateral 


OA 


ZjU3 


Unweighted lateral 


yi 


ZoUO 


Unweighted lateral 


y/ 


ZoU/ 


Unweighted lateral 


y3 


ZoUo 


Unweighted lateral 


y4 


oil 1 


Unweighted lateral 


yj 


oil 
ZoiZ 


Unweighted lateral 


yo 


oil 1 


Unweighted lateral 


y / 


oil /I 


Unweighted lateral 


no 

yo 


0101 
ZoZl 


Unweighted lateral 


QQ 

yy 


0100 

ZoZZ 


Unweighted lateral 


100 


2323 


Unweighted lateral 


101 


2341 


Unweighted lateral 


102 


2391 


Unweighted lateral 


103 


2392 


Unweighted lateral 


104 


2405 


Unweighted lateral 


105 


2407 


Unweighted lateral 


106 


2411 


Unweighted lateral 


107 


2413 


Unweighted lateral 



Gamma rays. 
Electrons. 
Positrons. 
Muons (+). 
Muons (-). 
Pions (+). 
Pions (— ). 
Kaons (+). 
Kaons (— ). 
Neutrons. 
Protons. 
Antiprotons. 
Nuclei. 

Other charged pcles. 
Other neutral pcles. 
e+ and e— 
mu+ and mu— 
pi+ and pi— 
K+ and K- 
All charged particles. 
All neutral particles. 
All particles. 

distribution: Gamma rays, 
distribution: Electrons, 
distribution: Positrons, 
distribution: Muons (+). 
distribution: Muons (— ). 
distribution: Pions (+). 
distribution: Pions (— ). 
distribution: Kaons (+). 
distribution: Kaons (— ). 
distribution: Neutrons, 
distribution: Protons, 
distribution: Antiprotons. 
distribution: Nuclei, 
distribution: Other charged pcles. 
distribution: Other neutral pcles. 
distribution: e+ and e— 
distribution: mu+ and mu— 
distribution: pi+ and pi- 
distribution: K+ and K— 
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Code 


Table name 


108 


2491 


Unweighted lateral 


109 


2492 


Unweighted lateral 


110 


2493 


Unweighted lateral 


111 
111 


ZSUl 


Energy distribution 


1 iz 




Energy distribution 


11 J 


ZSUO 


Energy distribution 


1 1 A 
114 


Z3U/ 


Energy distribution 


1 1 J 


ZSUo 


Energy distribution 


1 1 A 

1 Id 


'>C1 1 

Z311 


Energy distribution 


11/ 


Z31Z 


Energy distribution 


1 1 

1 lo 


Zslo 


Energy distribution 


iiy 


/I 

Zsl'l 


Energy distribution 


1 OA 

IzU 


ZdZi 


Energy distribution 


1 1 
IZl 


TOT 
Z3ZZ 


Energy distribution 


Izz 


Zdzj 


Energy distribution 


IzJ 


zs'll 


Energy distribution 




2S91 


THn(^ro\/ HiQtnViiition 

J_/llti^y UlSLilUULlVJll 


125 


2592 


Energy distribution 


126 


2705 


Energy distribution 


127 


2707 


Energy distribution 


128 


2711 


Energy distribution 


129 


2713 


Energy distribution 


130 


2791 


Energy distribution 


131 


2792 


Energy distribution 


132 


2793 


Energy distribution 


1 

LJJ 


ZoUl 


Unweighted energy 


134 


ZoU3 


Unweighted energy 


1 JJ 


ZoUo 


Unweighted energy 


13d 


ZoU/ 


Unweighted energy 


1 'in 


ZoUo 


Unweighted energy 


13b 


Zoll 


Unweighted energy 




781 7 
ZolZ 


Unweighted energy 


140 


2813 


Unweighted energy 


141 


2814 


Unweighted energy 


142 


2821 


Unweighted energy 


143 


2822 


Unweighted energy 


144 


2823 


Unweighted energy 


145 


2841 


Unweighted energy 


146 


2891 


Unweighted energy 


147 


2892 


Unweighted energy 



distribution: All charged particles, 
distribution: All neutral particles, 
distribution: All particles. 

at ground: Gamma rays. 

at ground: Electrons. 

at ground: Positrons. 

at ground: Muons (+). 

at ground: Muons (— ). 

at ground: Pions (+). 

at ground: Pions (— ). 

at ground: Kaons (+). 

at ground: Kaons (— ). 

at ground: Neutrons. 

at ground: Protons. 

at ground: Antiprotons. 

at ground: Nuclei. 

at ground: Other charged pcles. 

at ground: Other neutral pcles. 

at ground: e+ and e— 

at ground: mu+ and mu— 

at ground: pi+ and pi— 

at ground: K+ and K— 

at ground: All charged particles. 

at ground: All neutral particles. 

at ground: All particles. 

distribution: Gamma rays, 
distribution: Electrons, 
distribution: Positrons, 
distribution: Muons (+). 
distribution: Muons (— ). 
distribution: Pions (+). 
distribution: Pions (— ). 
distribution: Kaons (+). 
distribution: Kaons (— ). 
distribution: Neutrons, 
distribution: Protons, 
distribution: Antiprotons. 
distribution: Nuclei, 
distribution: Other charged pcles. 
distribution: Other neutral pcles. 
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Code Table name 



148 
149 
150 
151 
152 
153 
154 

155 
156 
157 
158 
159 
160 
161 
162 

163 
164 
165 
166 
167 
168 
169 
170 
171 
172 
173 
174 
175 
176 
177 
178 
179 
180 
181 
182 
183 
184 
185 
186 
187 



2905 
2907 
2911 
2913 
2991 
2992 
2993 

3001 
3005 
3007 
3091 
3092 
3291 
3292 
3293 
5001 
5005 
5006 
5007 
5008 
5011 
5012 
5013 
5014 
5021 
5022 
5023 
5041 
5091 
5092 
5205 
5207 
5211 
5213 
5291 
5292 
5293 
5501 
5511 
5513 



Unweighted energy distribution: e+ and e— 
Unweighted energy distribution: mu+ and mu— 
Unweighted energy distribution: pi+ and pi- 
Unweighted energy distribution: K+ and K— 
Unweighted energy distribution: All charged particles. 
Unweighted energy distribution: All neutral particles. 
Unweighted energy distribution: All particles. 

Mean arrival time distribution: Gamma rays. 

Mean arrival time distribution: Electrons and positrons. 

Mean arrival time distribution: Muons. 

Mean arrival time distribution: Other charged pcles. 

Mean arrival time distribution: Other neutral pcles. 

Mean arrival time distribution: All charged particles. 

Mean arrival time distribution: All neutral particles. 

Mean anival time distribution: All particles. 



versus shower number, 
versus shower number. 
+ versus shower number. 

- versus shower number. 

- versus shower number. 

- versus shower number. 

- versus shower number. 

- versus shower number. 



and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 


and 


energy 


of 



versus shower number, 
nu— versus shower numbe 

— versus shower number. 

- versus shower number. 



Xmax and Nmax (charged particles) versus shower number. 
First interact, depth and primary energy versus shower number. 
Zenith and azimuth angles versus shower number. 
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The AIRES object library 



The AIRES object library is a collection of modules that are useful in several applications, including 
(but not limited to) special primary modules (see section ^7^ , and output file processing, particularly 
compressed files generated by the AIRES compressed i/o unit (CIO). Most of the routines were es- 
pecially written for these purposes, but some of them are of general nature and are also used by the 
simulation and/or summary programs. 



D.1 C interface 

The modules of the AIRES object library are callable from a C program. In general the calling state- 
ment is similar to the FORTRAN one, taking into account that all arguments are passed by reference. 
That means that the actual arguments must be pointers to the corresponding data items. 

This requirement is made evident when describing the different routines by placing an ampersand 
(&) before the corresponding arguments. The experienced C programmer will understand, however, 
that this character is not required in actual calling statements containing pointer variables as argu- 
ments. The following example illustrates this point: 

int *channel, *vrb, *irc; 
int recnumber; 
int crogotorec ; 

if (crogotorec (channel, Srecnumber, vrb, ire)) { . . . 

All the arguments of crogotorec are defined as pointers, except recnumber which is declared as an 
integer variable. The & placed before this argument ensures that this variable be passed by reference 
to the called routine. 

In general, all the FORTRAN routines of the library can be directly called from a C program. In 
a few cases it was necessary to write special C routines, which were named appending a "c" to the 
original FORTRAN name, as in the case of opencrofile that must be called opencrofilec from a C 



program (see page [171)) 
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It is also worthwhile mentioning that some FORTRAN compilers do place an underscore (_) after 
the names of the routines. In such cases this character must be manually appended to all the routines 
used within the C program, excluding, of course, all the special C routines of the previous paragraph. 

D.2 List of most frequently used library modules. 

In this appendix we list the definitions of the most frequently used routines, alphabetically ordered. 
At each case the FORTRAN as well as the C calling statements are placed. 

cioclose 

FORTRAN call cioclose 
C cioclose; 

Closing all the currently already opened CIO files. 

cioclosel 

FORTRAN call cioclosel (channel) 
C cioclosel (Schannel) ; 

Closing an already opened CIO file. 

Arguments: 

channel (Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 
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ciorinit 



FORTRAN call ciorinit (inilevel , codsys, vrb, ire) 
C ciorinit (Sinilevel , &codsys, &vrb. Sire); 

Initializing the AIRES compressed I/O system for reading data. This routine must be invoked 
at the beginning of every program using the compressed I/O system routines. 

Arguments: 

inilevel {Input, integer) Initialization switch. If inilevel is zero or negative, all needed initial- 
ization routines are called. If positive only the CIO system is initialized (The other rou- 
tines must be called within the invoking program, before calling ciorinit: inilevel = 1 
means complete cio initialization, while inilevel > 1 implies only particle coding initial- 
ization. This last case allows changing the particle coding system at any moment during 
a CIO processing session. 

codsys {Input, integer) Particle coding system identification. This variable permits selecting 



among several particle coding systems supported by AIRES (see table [4.7[ ). The menu of 
available systems is the following: 

AIRES internal coding system. 

1 AIRES internal coding for elementary particles and decimal nuclear notation {code = 
^ + 100 * Z). 

4 Particle Data Group coding system [|^] extended with decimal nuclear notation.]^ 



5 CORSIKA program particle coding system [28]. 



6 GEANT particle coding system [ 3 1 1 



8 SIBYLL particle coding system extended with decimal nuclear notation. 

9 MOCCA style particle coding system, extended with decimal nuclear notation. 
- Any other value is equivalent to codsys = 1. 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages ai^e printed; eiTor conditions are communicated to the calling program via the 
return code. If vrb is positive error messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

ire {Output, integer) Return code. means successful return. 1 means that an invalid particle 
coding system was specified by codsys (in this case the default coding system is used). 



'For nuclei the notation: code = A-\- 100000 * Z, is used. 
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ciorshutdown 

FORTRAN call ciorshutdown 
C ciorshutdown; 



Terminating (in an ordered fashion) a compressed file analysis session. This routine should be 
invoked at the end of every CIO processing program. 
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crofieldindex 



FORTRAN idx = crofieldindex (channel, rectype, fieldname, 

vrb, datype, ire) 

C idx = crofieldindex (&channel, &rectype, 

fifieldname, &vrb, Sdatype, 
Sire) ; 



Returning the index corresponding to a given field within a compressed file record. It is conve- 
nient to use this routine to set integer variables, and use them to manage the data returned by 



getcrorecord, as explained in section [4.2.2| (page |88| ). 
Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

rectype {Input, integer) Record type (0 for default record type). 

fieldname {Input, character string) First characters of field name (enough characters must be 
provided to make an unambiguous specification). 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages ai^e printed; eiTor conditions are communicated to the calling program via the 
return code. If vrb is positive eiTor messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

datype {Output, integer) The data type that corresponds to the specified field: 1 for integer 
data, 2 for date-time data, and 3 for real data. 

ire {Output, integer) Return code. means successful return. 



Returned value: {Integer) The field index. Zero if there was an error. 
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crofileinfo 

FORTRAN call crofileinfo (channel, ouflag, vrb, ire) 
C crofileinfo (&channel, &ouflag, &vrb. Sire); 

Printing information about the records of an already opened compressed file. This routine 
retrieves information about the complete record structure of the corresponding file: How many 
record types are defined, and for each record type the number of fields and a list of their names 
and relative logical positions. The ordering in the list of fields is equal to the ordering of data in 
the integer and real arrays returned by routine getcrorecord when reading a record of the same 
type. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

ouflag {Integer, input) Logical output unit(s) selection flag. See routine croheaderinfo. 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; error conditions are communicated to the calling program via the 
return code. If vrb is positive eiTor messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar- to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

ire {Output, integer) Return code. means successful return. 
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crofileversion 

FORTRAN ivers = crofileversion (channel) 
C ivers = crofileversion (&channel) ; 

Returning the AIRES version used to write an already opened compressed file. 
Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

Returned value: {Integer) The corresponding version in integer format (for example the num- 
ber 01040200 for version 1.4.2,01040201 for version 1.4.2a, etc.). If the file is not opened 
or if there is an error, then the return value is negative. 
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crogotorec 



FORTRAN okflag = crogotorec (channel, 

ire) 

C okflag = crogotorec (Schannel 

Sire) ; 



recnumber, vrb. 



firecnumber, &vrb. 



Positioning the file after a given record. This routine, used in connection with crorecnumber, 
allows emulating direct access to compressed files. Notice however that a completely random 
access regime with very large files may eventually imply longer processing times. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

recnumber {Input, integer) The record number. A negative value is taken as zero. 

If recnumber < 0, the return code is always set to zero for successful operations (Notice 
that in this case the file will be positioned at the beginning of the data records). 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; error conditions are communicated to the calling program via the 
return code. If vrb is positive error messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal eiTor takes place. 

ire {Output, integer) Return code. The meanings of the different values that can be returned 
are as explained for routine getcrorecord. When the return code is a record type, it 
corresponds to the record type of the last scanned record. 



Returned value: {Logical) True if the positioning was successfully done. False otherwise. 
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croheaderlinfo 

FORTRAN call croheaderlinfo (ouf lag) 
C croheaderlinfo (&ouf lag) ; 



Getting information from an already read compressed file header. The information is printed 
into the standard output channel or into a file, accordingly with the value taken by ouflag. 

Since the header data is of global nature, the data printed out by this routine corresponds to the 
most recently opened compressed file. 

Arguments: 



ouflag {Integer, input) Logical output unit(s) selection fiag. See routine croheaderinfo. 
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croheaderinfo 

FORTRAN call croheaderinfo (ouf lag, vrb, ire) 
C croheaderinfo (&ouf lag, &vrb. Sire); 

Printing a summary of the information contained in the header of the most recently opened 
compressed file. 

Arguments: 

ouflag {Input, integer) Logical output unit(s) selection flag: or negative means FORTRAN 
unit 6 only, 1 means unit 7 only, 2 means both units 6 and 7, 3 means unit 8 only, oufiag > 
8 means unit ouflag only. FORTRAN unit 6 corresponds to the standard output channel. 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; error conditions are communicated to the calling program via the 
return code. If vrb is positive error messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal eiTor takes place. 

ire {Output, integer) Return code. means successful return. 
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croinputdataO 

FORTRAN call croinputdataO (intdat a, realdata, shprimcode, 

shprimwt ) 

C croinputdataO (Sintdata [1 ] , &realdata[l] , 

& shprimcode [1 ] , & shprimwt [1] ) ; 



Copying into arrays some header data items corresponding to the most recently opened com- 
pressed file. Notice that some additional input parameters must be retrieved using routines 



getinpreal, getinpint or getinpswitch (see pages |158|-|161|). 
Arguments: 

intdata {Output, integer, array(*)) Integer data array. The calling program must provide 
enough space for it. The following list describes the different data items: 

1 Number of different primary particles. 
2-4 Reserved for future use. 
5 Primary energy distribution: fixed energy; 1 varying energy. 



6 Zenith angle distribution: 0, fixed angle; 1, sine distribution (equation ( |3.4[ )) ; 



2, sine-cosine distribution (equation (3.6)) 



7 Azimuth angle distribution: (10), fixed angle (geographic azimuth); 1 (11), 
varying angle (geographic azimuths). 

8 Number of observing levels. 



9 Atmospheric model label (See page |110[ ). 

10-14 Reserved for future use. 

15 First shower number 

realdata {Output, double precision, array(*)) Real data an^ay. The calling program must 
provide enough space for it. The following list describes the different data items: 

1 Minimum primary energy (GeV). 

2 Maximum primary energy (GeV). 

3 Exponent 7 of energy distribution (equation (3.2)). 

4 Minimum zenith angle (deg). 

5 Maximum zenith angle (deg). 

6 Minimum azimuth angle (deg). 

7 Maximum azimuth angle (deg). 

8 Thinning energy parameter.^ 



^The thinning energy parameter, tp, must be interpreted as follows: When positive, it gives the absolute thinning energy 
in GeV. Otherwise it indicates a relative thinning specification, being Eth = |tp|i5primary 



144 



Appendix D. The AIRES object library 



9 Injection altitude (m)J^ 

10 Injection depth (g/cm^). 

1 1 Ground altitude (m). 

12 Ground depth (g/cm^). 
13-14 Reserved for future use. 

15 Altitude of first observing level (m). 

16 Vertical depth of first observing level (g/cm^). 

17 Altitude of last observing level (m). 

18 Vertical depth of last observing level (g/cm^). 

19 Distance between consecutive observing levels in g/cm^. 

20 Site latitude (deg). 

21 Site longitude (deg). 

22 Geomagnetic field strength, F, (nT). 

23 Local geomagnetic inclination, I, (deg). 

24 Local geomagnetic declination, D, (deg). 

25 Amplitude of random fluctuation of magnetic fielcQ. 
26-29 Reserved for future use. 

30 Minimum lateral distance used for ground particle histograms (m). 

31 Maximum lateral distance used for ground particle histograms (m). 

32 Minimum energy used for histograms (GeV). 

33 Maximum energy used for histograms (GeV). 
34-35 Reserved for future use. 

36 Minimum radial distance parameter for the most recently opened compressed 
file (m). 

37 Maximum radial distance parameter for the most recently opened compressed 
file (m). 

shprimcode {Output, integer, array(*)) For i from 1 to intdata(l), shprimcode(i) gives 
the corresponding primary particle code. The coding system used is the one defined when 
starting the cio system. 

shprimwt {Output, double precision, array(*)) For i from 1 to intdata(l), shprimvift(«) 
gives the corresponding primary particle weight. This weight is 1 in the single primary 
case. 



' Measured vertically, starting from the intersection point between the sea level and the line that goes form the Earth's 
center to the particle injection point, i.e., in figure [2. l|. 

■*The magnetic fluctuation parameter, /p, must be interpreted as follows: When positive, it gives the absolute fluctuation 
in nT. Otherwise it indicates a relative fluctuation specification, being AB = F. 



Appendix D. The AIRES object library 



145 



crooldata 

FORTRAN call crooldata (vrb, nobslev, olzv, oldepth, 

ire) 

C crooldata (&vrb, Snobslev, &olzv[l] , 

&oldepth[l] , &irc) ; 



Calculating observing levels information from data contained in a compressed data file header. 

Since the header data is of global nature, the data used by this routine corresponds to the most 
recently opened compressed file. 

Arguments: 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no eiTor or informative 
messages are printed; error conditions are communicated to the calling program via the 
return code. If vrb is positive error messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal eiTor takes place. 

nobslev {Output, integer) The number of observing levels. 

olzv {Output, double precision, array(*)) Altitudes (in m) of the corresponding observing 
levels, from 1 to nobslev. The calling program must ensure that there is enough space for 
this aiTay. 

oldepth {Output, double precision, array(*)) Vertical atmospheric depth (in g/cm^) of the 
corresponding observing levels, from 1 to nobslev. The calUng program must ensure that 
there is enough space for this array. 

ire {Output, integer) Return code. means successful return. 
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croreccount 

FORTRAN call croreccount (channel, vrb, nrtype, nrec, ire) 
C croreccount (&channel, &vrb, &nrtype[0], &nrec. 

Sire) ; 



Counting the records of a compressed file starting from the first non-read record. Once the file 
was scanned, the corresponding I/O channel is left in "end of file" status. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no eiTor or informative 
messages are printed; error conditions ai^e communicated to the calling program via the 
return code. If vrb is positive eiTor messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

nrtype {Output, integer) The highest record type defined for the file (record types range from 
zero to nrtype). 

nrec {Output, integer, array(0:nrtype)) For each record type, the number of records found. 
No check is made to ensure that the length of the array is enough to store all the data 
items. 

ire {Output, integer) Return code. means successful return. 
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crorecfind 

FORTRAN okflag = crorecfind (channel, intype, vrb, 

infieldl, rectype) 

C okflag = crorecfind (Schannel, &intype, &vrb, 

Sinfieldl, &rectype) ; 



Reading records until getting a specified record type. The compressed file associated with 
channel is scanned until a record of type intype is found. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

intype {Input, integer) Record type to find. 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; enw conditions are communicated to the calling program via the 
return code. If vrb is positive eiTor messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

infieldl {Output, integer) If intype is zero, this variable contains the current value of the 
first integer field of the last scanned record (which will be, in general, a particle code). 
Otherwise it is set to zero. 

rectype {Output, integer) Last scanned record type and return code. This argument contains 
the same information as argument ire of routine getcrorecord. Notice that in the case of 
successful return, rectype is equal to intype. 

Returned value: {Logical) True if the last record was successfully read. False otherwise (End 
of file or I/O error). 
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crorecinfo 

FORTRAN call crorecninfo (channel, poskey, ouflag, vrb, 

ire) 

C crorecninfo (Schannel, Sposkey, &ouflag, &vrb. 

Sire) ; 



Printing information about the total number of records within an already opened compressed 
file. The file is scanned starting after the last record already read to count the number of records 
of each type that were written into it. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

poskey {Input, integer) Positioning key. This parameter allows to control the file positioning 
after returning from this routine: If zero or negative the file remains positioned at the 
"end of file" point, if 1 at the beginning of data, and if greater than 1 , at the position found 
before the call (This last option may eventually imply a significant increase in processing 
time for very lai^ge files). 

ouflag {Integer, input) Logical output unit(s) selection flag. See routine croheaderinfo. 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; error conditions are communicated to the calling program via the 
return code. If vrb is positive eiTor messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

ire {Output, integer) Return code. means successful return. 
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crorecnumber 

FORTRAN recno = crorecnumber (channel, vrb, ire) 

C recno = crorecnumber (Schannel , &vrb. Sire); 

This function returns the current record number corresponding to an already opened com- 
pressed file. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; error conditions are communicated to the calling program via the 
return code. If vrb is positive eiTor messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
enor messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

ire {Output, integer) Return code. means successful return. 

Returned value: {Integer) The record number. If the file is not ready (closed or end of file), 
then — 1 is returned. 
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crorewind 

FORTRAN call crorewind (channel , vrb, ire) 
C crorewind (Schannel , &vrb, &irc) ; 



"Rewinding" an already opened compressed file. The file is positioned just before the first data 
record. In other words, the file is system rewound and its header is re-scanned so the file pointer 
remains located at the beginning of the record data stream. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no eiTor or informative 
messages are printed; error conditions ai^e communicated to the calling program via the 
return code. If vrb is positive eiTor messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages wiU be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

ire {Output, integer) Return code. means successful return. 
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crospcode 

FORTRAN isspecial = crospcode (pcode, splabel) 
C isspecial = crospcode (&pcode, Ssplabel) ; 

This logical function determines whether or not a given particle code corresponds to a special 
primary particle. 

Arguments: 

pcode {Input, integer) The particle code to check. 

splabel {Output, integer) Label associated to the special particle, or zero if the code does not 
corresponds to a special particle. This variable is useful for further use with other library 
routines, and should not be set by the calling program. 

Returned value: {Logical) True if the input code corresponds to a special primary particle. 
False otherwise. 
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crotaskid 

FORTRAN call crotaskid (taskname, tasknamelen, 

taskversion, startdate) 
C crotaskidc (& taskname, &tasknainelen, 

Staskversion, &startdate) ; 

Getting task name and starting date for the task corresponding to the most recently opened 
compressed file. 

Arguments: 

taskname {Output, string) The task name. The calhng program must ensure there is enough 
space to store the string. 

tasknamelen {Output, integer) Length of task name. 

tasknamelen {Output, integer) Task version. 

tasknamelen {Output, string) Task starting date in the format "dd/Mmm/yyyy hh:mm:ss" (20 
characters). 
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fitghf 

FORTRAN call fitghf (bodataO, eodataO, depths, 

nallch, weights, ws, minnmax, 
nininratio, bodataeff, eodataeff, 
nmax, xmax, xO, lambda, sqsum, 
ire) 

C fitghf (SbodataO, &eodataO, &depths[l], 

&nallch[l], &weights[l], &ws, 
&ininnmax, Snminratio, &bodataeff, 
&eodataeff, &nmax, &xmax, &xO, 
& lambda, & sqsum, &irc) ; 



Performing a 4-parameter nonlinear least squares fit to evaluate the parameters N^^,^, Xmax. 
Xq and A of the Gaisser-Hillas function of equation (p~T|). The fit is done using the Levenberg- 



Mardquardt algorithm, as implemented in the pubUc domain software library Netlib ||10p. 
Arguments: 

bodataO, eodataO {Input, integer) Positive integer parameters defining the number of data 
points to use in the fit. 

depths (Input, double precision, array(eodataO)) Depths of the observing levels used in the 

fit. Only the range (bodataO:eodataO) is used, 
nallch {Input, double precision, array(eodataO)) Number of charged particles crossing the 

different levels. Only the range (bodataO:eodataO) is used, 
weights {Input, double precision, array(eodataO)) Positive weights to be assigned to each 

one of the data points. Only the range (bodataO:eodataO) is used, 
ws {Input, integer) If ws = 2, the weights are evaluated internally (proportionally to the 

square root of the number of particles). If ws = 1 they must be provided as input data. If 

ws = 2 the array weights is not used. 

minnmax {Input, double precision) Thr eshold value for the maximum number of particles in 
the input data set. The fit is not performed if the maximum number of particles is below 
this parameter. If minnmax is negative, it is taken as zero. 

nminratio {Input, double precision) Positive parameter used to determine the end of the data 
set. Must be equal or greater than 5. Once the maximum of the data set is found, the 
points located after this maximum up to the point where the number of charged particles 
is less than the maximum divided nminratio. The remaining part of the data is not taken 
into account in the fit. A similar analysis is performed with the points located before the 
maximum. The recommended value is 100. A very large value will enforce inclusion of 
all the data set. 
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bodataeff, eodataeff {Output, integer) The actual range of data points used in the fit. 

nmax {Output, double precision) Estimated number of charged particles at the shower max- 
imum (parameter A^max)- If no fit was possible, then the value coming from a direct 
estimation from the input data is returned. 

xmax {Output, double precision) Fitted position of the shower maximum, Xmax^ in g/cm^. 
If no fit was possible, then the value coming from a direct estimation from the input data 
is returned. 

xO {Output, double precision) Fitted position of the point where the Gaisser-Hillas function 
is zero (parameter Xq), expressed in g/crc?. 

lambda {Output, double precision) Fitted parameter A, in g/crc?. 

sqsum {Output, double precision) The resulting normalized sum of squares: 



where is the number of data points used in the fit, and A^^^^ {N^'^^^) represent the 



depths). 

ire {Output, integer) Return code. Zero means that the fit was successfully completed. 




i=l 



(D.l) 



set of particle numbers given as input (returned from equation ^J] for the corresponding 
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getcrorecord 

get crorecord (channel , int fields, 

realfields, altrec, vrb, 
ire) 

getcrorecord (&channel, Sintf ields [1] , 
&realf ields [1] , Saltrec, 
&vrb. Sire) ; 

Reading a record from a compressed data file already opened. This routine can be used to read 
records from every kind of compressed file: The routine automatically processes the records 
without needing any user-level specification beyond file identity (parameter channel). The 
logical returned value (here assigned to logical variable okflag) permits determining whether 
or not the read operation was successful. The chai^acteristics of the read record aie informed 
via the return code (ire), and the arrays intfields and realfields contain the corresponding data 
items. Their contents depend on the file being processed and on the record type. The auxiliary 
routines crofileinfo and crofieldindex are useful to process adequately the returned data at each 
case. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

intfields {Output, integer, array(*)) Integer fields of the last read record. This includes the 
non-scaled integer quantities and (in the last positions) the date-time specification(s), if 
any. The calling program must provide enough space for this aiTay (The minimum di- 
mension is the maximum number of fields that can appear- in a record plus 1). Positions 
beyond the last integer fields are used as scratch working space. The meaning of each 
data item within this an^ay varies with the class of file processed and with the record type 
(see also argument ire and routine crofileinfo). 

realfields {Output, double precision, array(*)) Real fields of the record. The calling program 
must provide enough space for this array. The meaning of each data item within this array 
varies with the class of file processed and with the record type (see also argument ire and 
routine crofileinfo). 

altrec {Output, logical) True if the corresponding record type is positive (alternative record 
type) False if the record type is zero (default record type). 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; error conditions are communicated to the calling program via the 
return code. If vrb is positive error messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 



FORTRAN okflag = 
C okflag = 
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error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

ire {Output, integer) Return code. means that a record with zero (default) record type was 
successfully read, i (z > 0) means that an alternative record of type i was successfully 
read. — 1 means that an end-of-file condition was got from the corresponding file. Any 
other value indicates a reading error (ire equals the system return code plus 10000). 

Returned value: {Logical) True if a record was successfully read. False otherwise (End of file 
or I/O eiTor). 
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getcrorectype 

FORTRAN okflag = getcrorectype (channel, vrb, infieldl, 

rectype) 

C okflag = getcrorectype (Schannel, &vrb, &infieldl, 

& rectype) ; 



Getting the record type of the record which is located next to the last read record of the com- 
pressed file identified by argument channel. 

The action of this routine consists in reading the first part of the record to obtain the record type, 
and then skip the remaining part to position the file at the end of the corresponding record. The 
use of this routine is recommended whenever only the record type is needed, since it is faster 
than getcrorecord. When additional data of an already scanned record is required, routine 
regetcrorecord can be used to re-scan the last processed one. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
corresponding file. This variable must be already set by means of routine opencrofile. 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; error conditions are communicated to the calling program via the 
return code. If vrb is positive error messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
enor messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal eiTor takes place. 

infieldl {Output, integer) If rectype is zero, this variable contains the current value of the 
first integer field of the record (which is, in general, a particle code). Otherwise it is set to 
zero. 

rectype {Output, integer) Record type and return code. This argument contains the same 
information as argument ire of routine getcrorecord. 

Returned value: {Logical) True if a record was successfully read. False otherwise (End of file 
or I/O eiTor). 
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getinpint 

FORTRAN value = getinpint (dirname) 
C value = getinpintc (Sdirname) ; 



Getting the current value for an integer (static) input parameter corresponding to the most 
recently opened compressed file. This routine is used to get from the current file's header those 



integer input parameters not returned by routine croinputdataO (see page 143). 
Arguments: 

dirname {Input, string) Name of the IDL directive associated with the parameter (can be 
abbreviated accordingly with the rules described in appendix |b|). 



Returned value: (integer) The cuiTent setting for the corresponding parameter In case of 
error the returned value is undefined. 
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getinpreal 

FORTRAN value = getinpreal (dirname) 
C value = getinprealc (&dirname) ; 

Getting the current value for a real (static) input parameter corresponding to the most recently 
opened compressed file. This routine is used to get from the cun^ent file's header those real 
input parameters not returned by routine croinputdataO (see page |143| ). 

Arguments: 

dirname {Input, string) Name of the IDL directive associated with the parameter (can be 
abbreviated accordingly with the rules described in appendix 

Returned value: (double precision) The cuiTcnt setting for the corresponding parameter In 
case of error the returned value is undefined. 
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getinpstring 

FORTRAN call getinpstring (dirname, value, slen) 
C getinpstringc (&dirname, Svalue, Sslen) ; 

Getting the current value for an input (static) character string corresponding to the most re- 
cently opened compressed file. 

Arguments: 

dirname {Input, string) Name of the IDL directive associated with the parameter (can be 
abbreviated accordingly with the rules described in appendix 

value {Output, string) The current parameter value. The calUng program must ensure that 
there is enough space to store the string. 

slen {Output, integer) Length of the current parameter value. On error, slen is negative. 



Appendix D. The AIRES object library 



161 



getinpswitch 

FORTRAN value = getinpswitch (dirname) 
C value = get inpswitchc (& dirname ) ; 



Getting the current value for an input (static) logical switch corresponding to the most recently 
opened compressed file. This routine is used to get from the current file's header those logical 
input parameters not returned by routine croinputdataO (see page |143| ). 

Arguments: 

dirname {Input, string) Name of the IDL directive associated with the parameter (can be 
abbreviated accordingly with the rules described in appendix 

Returned value: (Logical) The cun^ent setting for the corresponding parameter In case of 
error the returned value is undefined. 
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grandom 

FORTRAN r = grandom () 
C r = grandom ( ) ; 



This function invokes the AIRES random number generator and returns a pseudo-random num- 
ber with normal gaussian distribution (zero mean and unit standard deviation). It is necessary 
to initialize the random series calling raninit before using this function. 

Returned value: {Double precision) The gaussian pseudo-random number. 
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idlcheck 

FORTRAN ikey = idlcheck (dirname) 
C ikey = idlcheckc (Sdirname) ; 

Checking a string to see if it matches any of the IDL instructions currently defined, that is, the 
ones corresponding to the most recently opened compressed file. 

Arguments: 

dirname {Input, string) Name of the IDL directive to be checked (can be abbreviated accord- 
ingly with the rules described in appendix 

Returned value: {Integer) If an en^or occurs, then the returned value will be negative. Other 
return values are the following: 

The string does not match any of the currently valid IDL instructions. 

1 The string matches a directive belonging to the "basic" instruction set with no pa- 
rameter(s) associated with it, for example Help. 

2 The string matches a directive belonging to the "basic" instruction set. If there is a 
parameter associated with the directive, then it can be obtained by means of routine 
croinputdataO. 

4 The directive corresponds to a real input parameter. The parameter can be retrieved 
by means of function getinpreal. 

6 The directive corresponds to an integer input parameter. The parameter can be re- 
trieved by means of function getinpint. 

8 The directive corresponds to a logical input parameter. The parameter can be re- 
trieved by means of function getinpswitch. 
10 The directive correspond to a string input parameter. The parameter can be retrieved 
by means of routine getinpstring. 
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nuclcode 

FORTRAN ncode = nuclcode (z, n, ire) 

C ncode = nuclcode(&z, &n, &irc) ; 

This routine returns the AIRES code of a nucleus of Z protons and N neutrons, as defined in 
page 

Arguments: 

z {Input, integer) The number of protons in the nucleus, 
n {Input, integer) The number of neutrons in the nucleus. 

ire {Output, integer) Return code. means that a valid pair of input parameters (Z, A^) was 
successfully processed. 3 means that the nucleus cannot be specified with the AIRES 
system. 5 means that either Z or N are out of allowed ranges. 



Returned value: {Integer) The nucleus code of equation ( |2.17| ). 
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nucldecode 

FORTRAN call nucldecode (ncode, z, n, a) 
C nucldecode (&ncode, &z, &n, &a) ; 



This routine returns the charge, neutron and mass numbers corresponding to a given AIRES 
nuclear code (see page [T9| ). 

Arguments: 



ncode {Input, integer) The AIRES nuclear code of equation ( |2.17| ). 
z {Output, integer) The number of protons in the nucleus, 
n {Output, integer) The number of neutrons in the nucleus, 
a {Output, integer) The mass number. 
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olcoord 

FORTRAN call olcoord (nobslev, olzv, groundz, injz, 

zenith, azimuth, xaxis, yaxis, 
zaxis, tshift, mx, my, ire) 
C olcoord (Snobslev, &olzv[l] , Sgroundz, 

&injz, Szenith, &azimuth, 
&xaxis[l], &yaxis[l], &zaxis[l], 
&tshift[l], &mx[l], &my[l], &irc) ; 

This routine evaluates the coordinates of the intersections of observing level surfaces with the 
shower axis, (xoi, yoi) zoi), i = 1, . . . , No, the corresponding time shifts, toi, and the coeffi- 
cients, nixi, niyi, of the plane tangent to the surface at the intersection point: 

z- ZQi = m^i{x - xoi) + myi{y - yoi), i = l,...,No. (D.2) 

Arguments: 

nobslev (Input, integer) The number of observing levels (No). 

olzv (Input, double precision, arraj(nobslev)) Altitudes (in m) of the corresponding ob- 
serving levels. 

groundz (Input, double precision) Ground altitude (in m). 
injz (Input, double precision) Injection altitude (in m). 
zenith (Input, double precision) Shower zenith angle (deg). 
azimuth (Input, double precision) Shower azimuth angle (deg). 

xaxis, yaxis, zaxis (Output, double precision, a/raj(nobslev)) Respectively xoi, yoi and 
zoi, i = 1, . . . ,No, coordinates (in m) of the intersection points between the observing 
level surfaces and the shower axis. 

tshift (Output, double precision, arraj(nobslev)) Observing levels time shifts, tQi, i = 
1, . . . , No, (in ns), that is, the amount of time a particle moving at the speed of light needs 
to go from the shower injection point to corresponding intersection point {xoi,yoi, zoi). 

mx, my (Output, double precision, arrajfnobslev)) Coefficients of the planes which are 
tangent to the observing levels and pass by the corresponding intersection points. 

ire (Output, integer) Return code. Zero means successful return. 
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olcrossed 

FORTRAN call olcrossed (olkey, updown, firstol, lastol) 
C olcrossed (&olkey, Supdown, &firstol, 

&lastol) ; 



This routine reconstructs the information contained in the crossed observing levels key, one of 
the data items saved at each particle record in any longitudinal tracking compressed file. 

This key encodes the first and last crossed observing observing levels and the direction of 



motion. The encoding formula defined in equation ( |4.6| ), where L, if and i/ correspond to 
olkey, firstol and lastol, respectively. 



The routine returns all the variables of the right hand side of equation ( |4.6D . The variable 
associated to Sud, updown is set in a slightly different way: It is be set to 1 when the particle 
goes upwards, and to — 1 otherwise. 

Arguments: 

olkey (Input, integer) Key with information about the crossed observing levels. 

updown (Output, integer) Up-down indicator: 1 if the particle is going upwards, — 1 other- 
wise. 

firstol (Output, integer) First observing level crossed (1 < firstol < 510). 
lastol (Output, integer) Last observing level crossed (1 < lastol < 510). 
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olcrossedu 

FORTRAN call olcrossedu (olkey, ux, uy, uz, firstol, 

lastol) 

C olcrossedu (&olkey, &ux, &uy, &uz, &firstol, 

Slastol) ; 

This routine is similar to olcrossed, but retrieves the information about the particle's direction 
of motion (up or down) in the form of an unitary vector. 

Arguments: 

olkey {Input, integer) Key with information about the crossed observing levels (See routine 
olcrossed). 

ux, uy {Input, double precision) x and y components of the unitary vector marking the parti- 
cle's direction of motion. 

uz {Output, double precision) z component of the direction of motion. Positive means up- 
wards motion. 

firstol {Output, integer) First observing level crossed (1 < firstol < 510). 
lastol {Output, integer) Last observing level crossed (1 < lastol < 510). 
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olsavemarked 

FORTRAN ismarked = olsavemarked (obslev, vrb, ire) 

C ismarked = olsavemarked (&obslev, &vrb. Sire) ; 



Logical function returning "true" if an observing level is marked to be saved into longitudinal 
files, "false" otherwise. An arbitrary subset of the defined observing levels can be selected for 



inclusion into the longitudinal compressed files (see page 123); this function allows to deter- 
mine if a given observing level was or not marked at the moment of performing the simulations 
that generated the corresponding compressed file. 

Arguments: 

obslev {Input, integer) The number of observing level. If it is out of range the returned value 
will always be "false". 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; enor conditions are communicated to the calling program via the 
return code. If vrb is positive error messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal eiTor takes place. 

ire {Output, integer) Return code. means successful return. 



Returned value: {Logical) "true" if the level is marked for file recording, "false" otherwise. 
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olvlslant 

FORTRAN call olv2slant (nobslev, olxv, XvO, zendis, 

zenl, zen2, groundz, olxs) 
C olv2 slant (&nobslev, &olxv[l], &XvO, &zendis, 

&zenl, &zen2, &groundz, &olxs[l]); 



Evaluating the slant depths of a set of observing levels. The slant depths are calculated along an 
axis starting at altitude zground, for the "segment" that ends at vertical depth XvO (XvO = is 
the top of the atmosphere). The integer variable zendis allows to select among fixed, sine and 



sine-cosine zenith angle distributions (see section [3.3.3| ). 
Arguments: 

nobslev {Input, integer) The number of observing levels (No). 

olxv {Input, double precision, arraj(nobslev)) Vertical atmospheric depths (in g/cm^) of 
the corresponding observing levels. 

XvO {Input, double precision) Vertical atmospheric depth (in g/cm^) of the point marking the 
end of the integration path. If XvO is zero, then the end of the integration path is the top 
of the atmosphere. 

zendis {Input, integer) Zenith angle distribution switch: - fixed zenith angle, 1 - sine 
distribution, 2 - sine-cosine distribution. 

zenl, zen2 {Input, double precision) Minimum and maximum zentih angles (degrees). If 
zendis is 0, then zen2 is not used and zenl gives the corresponding fixed zenith angle. 

groundz {Input, double precision) Ground altitude (in m). 

olxs {Output, double precision, array (nohsle-v)) Slant atmospheric depths (in g/cm^) of 
the corresponding observing levels. 
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opencrofile 

FORTRAN call opencrofile (wdir, filename, headerl, 

logbase, vrb, channel, ire) 
C opencrof ilec (Swdir , Sfilename, &headerl, 

&logbase, &vrb, &channel, &irc) ; 



Opening a CIO file for reading. This routine performs both the system open operation and file 
header processing and checking. 

Arguments: 

wdir {Input, character string) The name of the directory where the file is placed. It defaults 
to the current directory when blank. 

filename {Input, character string) The name of the file to open. 

Iieaderl {Input, integer) Integer switch to select reading (greater than or equal to 0) or skip- 
ping (less than 0) the first part of the header. 

logbase {Input, integer) Variable to control the logarithmically scaled fields of the file records. 
If logbase is less than 2, then the returned logarithms will be natural logarithms. Other- 
wise base logbase will be returned (decimal ones if logbase = 10). 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; error conditions are communicated to the calling program via the 
return code. If vrb is positive eiTor messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal eiTor takes place. 

channel {Output, integer) File identification. This variable should not be changed by the 
calling program. It must be used as a parameter of the reading and closing routines in 
order to specify the con^esponding file. 

ire {Output, integer) Return code. means successful return. 1 means successful return 
obtained with a file that was written with a previous AIRES version. 10 means that the 
file could be opened normally, but that it seems not to be a valid AIRES compressed 
data file, or is a corrupted file; 12 invalid file header; 14 not enough size in some of 
the internal arrays; 16 format incompatibilities. 20: too many compressed files already 
opened. 300 < ire < 400 indicates a version incompatibility (when processing files 
written with other AIRES version) or invalid version field (coiTupt header). Any other 
value indicates an opening / header-reading error (ire equals the system return code plus 
10000). 
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raninit 

FORTRAN call raninit (seed) 
C raninit (&seed) ; 

Initialization of the uniform pseudo-random number generator. This routine must be called 
before the first invocation of grandom, urandom, or urandomt. 

Arguments: 

seed (Input, double precision) Seed to initialize the random series. If seed does not belong 
to the interval (0, 1), then the seed actually used for initialization is internally generated 
using the system clock. 



Appendix D. The AIRES object library 



173 



regetcrorecord 

FORTRAN okflag = regetcrorecord (channel, int fields, 

realfields, altrec, vrb, 
ire) 

C okflag = regetcrorecord (&channel, &intf ields [1 ] , 

&realfields [1] , Saltrec, 
&vrb. Sire) ; 



Re-reading the cuiTent record. The input and output parameters of this routine are equivalent to 
the respective arguments of routine getcrorecord. The difference between this routine and the 
mentioned one is that regetcrorecord re-scans the last read record instead of advancing across 
the input file, regetcrorecord is thought to be used jointly with getcrorectype, crorecfind and 
other related procedures. 

Arguments: 

channel {Input, integer) Variable that uniquely identifies the I/O channel assigned to the 
coiTcsponding file. This variable must be already set by means of routine opencrofile. 

intfields {Output, integer, array(*)) Integer fields of the record. For a complete description 
of this argument see routine getcrorecord 

realfields {Output, double precision, array(*)) Real fields of the record. For a complete 
description of this argument see routine getcrorecord 

altrec {Output, logical) Alternative/default record type label. See getcrorecord 

vrb {Input, integer) Verbosity control. If vrb is zero or negative then no error or informative 
messages are printed; eiTor conditions ai^e communicated to the calling program via the 
return code. If vrb is positive eiTor messages will be printed: vrb = 1 means that 
messages will be printed even with successful operations, vrb = 2,3 means that only 
error messages will be printed, vrb > 3 is similar to vrb = 3, but with the additional 
action of stopping the program if a fatal error takes place. 

ire {Output, integer) Return code. For a complete description of this argument see routine 
getcrorecord 

Returned value: {Logical) True if a record was successfully re-read. False otherwise (EOF or 
I/O error). 
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splstint 

FORTRAN call splstint (csys , xl, yl, zl, ire) 
C splstint (&csys, &xl, &yl, &zl. Sire); 



Setting manually the position of the first interaction. When using special primary particles 
processed by external modules which may inject more that a single primary, AIRES cannot 
determine automatically the point where the first interaction takes place, and will take it as 
equal to the injection point unless it is set explicitly using splstint. This routine should be 
used only within modules designed to process special primaries, and following the guidelines 



of section 3.5 (page 66) 



Arguments: 

csys {Input, integer) Parameter labelling the coordinate system used, csys = selects the 
AIRES coordinate system, csys = 1 selects the shower axis-injection point system de- 



fined in section 3.5 



xl, yl, zl {Input, double precision) Coordinates of the first interaction point with respect to 
the chosen coordinate system (in meters). 

ire {Output, integer) Return code. means normal return. 
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spaddnuU 

FORTRAN call spaddnull (pener, pwt, ire) 
C spaddnull (Spener, &pwt, &irc) ; 



Adding a null (unphysical) particle to the list of primaries to be passed from the external module 
to the main simulation program. This "particle" will not be propagated, but its energy will be 
added to the unphysical particle counter included in the shower energy balance. This routine 
should be used only within modules designed to process special primaries, and following the 



guidelines of section |3^ (page pq ). 
Arguments: 

pener {Input, double precision) Energy (GeV). 

pwt (Input, double precision) Null particle weight. Must be equal or greater than one. 
ire (Output, integer) Return code. means normal return. 
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spaddpO 

FORTRAN call spaddpO (pcode , pener, csys, ux, uy, uz, 

pwt, ire) 

C spaddpO (Spcode, Spener, &csys, &ux, &uy, 

&UZ, &pwt. Sire) ; 



Adding a primary particle to the list of primaries to be passed from the external module to the 
main simulation program. This routine should be used only within modules designed to process 



special primaries, and following the guidelines of section 3.5 (page 56). 
Arguments: 

pcode {Input, integer) Particle code, accordingly with the AIRES coding system described in 



section [2.2. 1| (page |19| ). 
pener {Input, double precision) Kinetic energy (GeV). 

csys {Input, integer) Parameter labelling the coordinate system used, csys = selects the 
AIRES coordinate system, csys = 1 selects the shower axis-injection point system de- 
fined in section 

ux, uy, uz {Input, double precision) Direction of motion with respect to the chosen coordinate 
system. The vector (ux, uy, uz) does not need to be normalized. 

pwt {Input, double precision) Particle weight. Must be equal or greater than one. 

ire {Output, integer) Return code. means normal return. 
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spaddpn 

FORTRAN call spaddpn (n, pcode, pener, csys, Idu, 

uxyz, pwt, ire) 
C spaddpn (Spcode, Spener, Scsys, &ldu, 

&uxyz[l][l], &pwt. Sire); 



Adding a set of n primary particles to the list of primaries to be passed from the external module 
to the main simulation program. This routine should be used only within modules designed to 
process special primaries, and following the guidelines of section (page | 

Arguments: 

n (Input, integer) The number of particles to add to the list. 

pcode (Input, integer, array(n)) Particle codes, accordingly with the AIRES coding system 



described in section 2.2.1 (page 19). 
pener (Input, double precision, array(n)) Kinetic energies (GeV). 

csys (Input, integer) Parameter labelUng the coordinate system used, csys = selects the 
AIRES coordinate system, csys = 1 selects the shower axis-injection point system de- 



fined in section 3.5 



Idu (Input, integer) Leading dimension of array uxyz; must be equal or greater than 3. 

uxyz (Input, double precision, array(ldu, n )0) Directions of motion with respect to the chosen 
coordinate system. The vectors (uxyz(l, i), uxyz(2, i), uxyz(3, i)), i = 1, . . . , n, do 
not need to be normalized. 

pwt (Input, double precision, array(n)) Particle weights. The weights must be equal or 
greater than one. 

ire (Output, integer) Return code. means normal return. 



^If uxyz is defined in a C environment, then its two dimensions should be swapped, i.e., double uxyz [n] [Idu] 
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speiend 

FORTRAN call speiend (retcode) 
C speiend (&retcode) ; 



Closing the interface for the special primary particle external process. This routine should be 
used only within modules designed to process special primaries, and following the guidelines 



of section ^ (page pq ). 
Arguments: 

retcode {Input, integer) Return code to pass to the main simulation program, retcode = 
means normal return. If retcode is not zero, a message will be printed and saved in the log 
file (extension .Igf). < |retcode| < 10, 10 < |retcode| < 20, 20 < |retcode| < 30, 
and |retcode| > 30 correspond, respectively, to information, warning, error and fatal 
messages. 
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speigetmodname 

FORTRAN call speigetmodname (mn, mnlen, mnfull, mnfullen) 
C speigetmodnamec (&mn, &mnlen, Smnfull, &mnfullen) ; 



Getting the name of the module invoked by the simulation program, that is, the one specified 
in the definition of the coiTesponding special particle. This routine should be used only within 



modules designed to process special primaries, and following the guidelines of section 3.5 



(page 66). 



Arguments: 

mn {Output, string ) Name of external module. The calling program must ensure there is 
enough space to store the string. 

mnlen (Output, integer) Length of external module name. 

mnfull (Output, string ) Full name of external module (Will be different of mn if the module 
was placed within one of the directories specified with the InputPath directive. The 
calhng program must ensure there is enough space to store the string. 

mnfullen (Output, integer) Length of full external module name. 
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speigetpars 

FORTRAN call speigetpars (parstring, pstrlen) 
C speigetparsc (&parstring, &pstrlen) ; 



Getting the parameter string specified in the IDL instruction that defines the corresponding 
special particle. This routine should be used only within modules designed to process special 
primaries, and following the guidelines of section 3.5 (page 56). 

Arguments: 

parstring {Output, string ) Parameter string. The calling program must ensure there is enough 
space to store the string. 

pstrlen (Output, integer) Length of parameter string. Zero if there are no parameters. 



Appendix D. The AIRES object library 



181 



speimv 

FORTRAN call speimv (mvnew, mvold) 
C speimv (Smvnew, &mvold) ; 



Setting and/or getting tiie external macro version. Tiiis routine should be used only within 



modules designed to process special primaries, and following the guidelines of section 3.5 



(page 66). 



Arguments: 

mvnew {Input, integer) Macro version number. Must be an integer in the range [1, 759375]. 
If mvnew is zero, then the macro version is not set. 

mvold {Output, integer) Macro version number effective at the moment of invoking the rou- 
tine. This variable will be set to zero in the first call to speimv. 
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spinjpoint 

FORTRAN call spinjpoint (csys, xO, yO, zO, tsw, tObeta, 

ire) 

C spin jpoint (Scsys, &xO, &yO, &zO, &tsw, 

StObeta, Sire) ; 



Setting the current injection point for primary particles. This routine should be used only 
within modules designed to process special primaries, and following the guidelines of section 



3.5 (page b§). 



Arguments: 

csys {Input, integer) Parameter labelling the coordinate system used, csys = selects the 
AIRES coordinate system, csys = 1 selects the shower axis-injection point system de- 



fined in section 3.5 



xO, yO, zO {Input, double precision) Coordinates of the injection point with respect to the 
chosen coordinate system (in meters). 

tsw {Input, integer) Injection time switch. If tsw is zero then tObeta is an absolute injection 
time; if tsw is 1, then the injection time is set as the time employed by a particle whose 
speed is tObeta x c to go from the original injection point to the intersection point of the 
shower axis with the plane orthogonal to that axis and containing the point (xO, yO, zO). 

tObeta {Input, double precision) The meaning of this argument depends on the cunent value 
of tsw. It can be the absolute injection time (ns) (time at original injection is taken as 
zero); or the speed of a particle divided by c. 

ire {Output, integer) Return code. means normal return. 
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speistart 

FORTRAN call speistart (showerno, primener, injpos, 

xvin j , zground, xvground, 
dgroundin j , uprim) 
C speistart (fishowerno, Sprimener, &injpos[l], 

Sxvinj, &zground, &xvground, 
Sdgroundinj, &uprim[l]); 



Starting the interface for the special primary particle external process. This routine should be 
used only within modules designed to process special primaries, and following the guidelines 



of section 3.5 (page 66) 



Arguments: 

showerno {Output, integer) Current shower number 
primener {Output, double precision) Primary energy (GeV). 

injpos {Output, double precision, array(3)) Position of the initial injection point with respect 
to the AIRES coordinate system (in meters). 

xvinj {Output, double precision) Vertical atmospheric depth of the injection point (in g/cm^). 

zground {Output, double precision) Altitude og ground level (in m.a.s.l.). 

xvground {Output, double precision) Vertical atmospheric depth of the ground surface (in 
g/cm^). 

dgroundinj {Output, double precision) Distance from the injection point to the intersection 
between the shower axis and the ground surface (in meters). 

uprim {Output, double precision, array(3)) Unitary vector in the direction of the straight line 
going from the injection point towards the intersection between the shower axis and the 
ground plane. 
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speitask 

FORTRAN call speitask (taskn, tasklen, tver) 
C speitaskc (&taskn, &tasklen, &tver) ; 



Getting the current task name and version. This routine should be used only within modules 



designed to process special primaiies, and following the guidelines of section ^ (page p6[ ). 
Arguments: 

taskn {Output, string ) Task name. The calling program must ensure there is enough space to 
store the string. 

tasklen {Output, integer) Length of task name. 

tver {Output, integer) Task name version. 
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spnshowers 

FORTRAN call spnshowers (totsh, firstsh, lastsh) 
C spnshowers (Stotsh, Sfirstsh, Slastsh) ; 



Getting the current values of the first and last shower, and total number of showers. This routine 
should be used only within modules designed to process special primaries, and following the 



guidelines of section |33| (page pq ). 
Arguments: 

totsh {Output, integer) Total number of showers for the current task, 
firstsh {Output, integer) Number of first shower 
lasttsh {Output, integer) Number of last shower. 
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sprimname 

FORTRAN call sprimname (pname, pnamelen) 
C sprimnamec (&pname, &pnamelen) ; 



Getting the name of the special primary particle specified in the corresponding IDL instruction. 
This routine should be used only within modules designed to process special primaries, and 



following the guidelines of section |33| (page pq ). 
Arguments: 

pname {Output, string) The name of the special particle. The calling program must ensure 
there is enough space to store the string. 

pnamelen (Output, integer) Length of paiticle name. 
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thisairesversion 

FORTRAN iavers = thisairesversion () 
C iavers = thisairesversion () ; 



Returning the current version of the AIRES hbrary. 

Returned value: (Integer) The corresponding version in integer format (for example the num- 
ber 01040200 for version 1.4.2, 01040201 for version 1.4.2a, etc.). 
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urandom 

FORTRAN r = urandom () 
C r = urandom ( ) ; 

This function invokes the AIRES random number generator and returns a pseudo-random num- 
ber uniformly distributed in the interval [0, 1). It is necessary to initialize the random series 
calling raninit before using this function. 

Returned value: {Double precision) The uniform pseudo-random number, 
urandomt 

FORTRAN r = urandomt (threshold) 
C r = urandomt (threshold) ; 

This function invokes the AIRES random number generator and returns a pseudo-random num- 
ber uniformly distributed in the interval [t, 1), where t is a specified threshold (0 < t < 1). It 
is necessary to initiaUze the random series calling raninit before using this function. 

Arguments: 

threshold {Input, double precision) The threshold t. 

Returned value: {Double precision) The uniform pseudo-random number. 
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xslant 

FORTRAN X = xslant 
C X = xslant 



(Xvert, XvO, cozenith, 
zground) 

(SXvert, &XvO, &cozenith, 
& zground) ; 



Converting vertical atmospheric depths into slant atmospheric depths. This routine evaluates 
the slanted path (in g/cw?) of equation (p^), starting (ending) at the point whose vertical depth 
is Xvert (XvO). The inclination of the integration path is controlled by parameters cozenith 
(cosine of the zenith angle) and zground (altitude, in meters, of the intersection between the 



oblique axis and the z-axis), as illustrated in figure ^Jj (page |11| ). 
Arguments: 

Xvert {Input, double precision) Vertical atmospheric depth (in g/crc?) of the point marking 
the beginning of the integration path. Must be positive. 

XvO {Input, double precision) Vertical atmospheric depth (in g/cw?) of the point marking the 
end of the integration path. If XvO is zero, then the end of the integration path is the top 
of the atmosphere. If XvO corresponds to a point located below the point corresponding 
to Xvert (XvO > Xvert), then the returned slant depth will be negative. 



cozenith {Input, double precision) Cosine of the zenith angle (see figure |2.l| ) corresponding 
to the integration line. Must be in the range (0, 1]. 

zground {Input, double precision) z-coordinate (in meters) of the intersection point between 
the oblique axis and the z-axis, which is normally coincident with the "ground altitude". 



Returned value: {Double precision) The slant atmospheric depth in g/cm^; or zero in case of 
enor or invalid argument. 



Appendix E 

Release notes 



This appendix contains a brief summary of the new developments that are included in the current 
version of AIRES (2.2.0), as well as a description of the differences with the previous release of the 
system (2.0.0). 

The number in brackets placed after directive names or library routines indicates the page where 



the corresponding directive/routine is described. Example: TaskName (127). 



E.1 Differences between AIRES 2.2.0 and AIRES 2.0.0 
Bugs 

A number of problems with AIRES 2.0.0 simulation program were detected or reported by several 
users. All the eiTors in the program's code -mostly minor bugs- were fixed and are no longer present 
in the current version of AIRES. Some of those bugs are: 

• Incorrect processing of some lambda baryons generated by QGSJET, significantly affecting 
about 1% of the showers. Was fixed. 

• A minor bug related with directive ExportTables was fixed. 
Algorithm modifications 

Energy losses. New parameterizations for the electron and positron energy losses. The new functions 
are based on GEANT continuous losses curves. 

Resampling. A resampling algorithm complements the thinning algorithm and selectively eliminates 
particles located near the shower axis to reduce the size of particle files (see page |^). 

Special primary particles. New feature to process primary particles that AIRES cannot propagate 



directly (see section |3.5| ). 
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The number in brackets placed after directive names indicate the page where the corresponding di- 
rective is described. 

New directives. 



AddSpecialParticle (109) 



ForceModelName (114) 



ResamplingRatio (124) 



SpecialParticLog (126). 



Directives that changed their syntax or behavior. 



• Primary Particle (121). 
Directives related to parameters which changed their default values. 



RLimsFile(124) 



AIRES object library 

The library was expanded by the addition of new routines: 



crospcode (151) 



fitghf (153) 



splstint(174) 



spaddnull(175) 



spaddp0(176) 



spaddpn (177) 



speiend (178) 



speigetmodname (179) 



speigetpars (180) 



speimv (181) 



spinjpoint (182) 



speistart (183) 



speitask (184) 



spnshowers (185) 



sprimname (186) 
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raninit,94, 162, 172, 188 
regetcrorecord, 94, 157, 173 
splstint, 72, 174, 191 
spaddnull, 72, 175, 191 
spaddpO, 68-71, 176, 191 
spaddpn, 72, 177, 191 
speiend, 68-72, 178, 191 
speigetmodname, 71, 179, 191 
speigetpars, 71, 180, 191 
speimv, 72, 181, 191 
speistart, 68-72, 183, 191 
speitask, 71, 184, 191 
spinjpoint, 72, 182, 191 
spnshowers, 71, 185, 191 
sprimname, 71, 186, 191 
thisairesversion, 91, 187 
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aireskill, 97 
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rmairesspool, 99 
AIRES runner system, 4 
AIRES site library, 46, 61, 109, 116, 125 
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converting program 
. airesrc initialization file, 95, 96, 99, 105 
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format 
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backwards compatibility, 73, 78 
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bremsstrahlung, viii, 3, 20, 22, 111 
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continuous energy losses, 190 
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crorecnumber, see AIRES object library, 
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energy distributions, 2, 26, 36, 64, 76, 112, 131 
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for single showers, 113 
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fault tolerant processing, 6, 56, 95 

file directories, see AIRES file directories 

first shower number, 79, 114 

f itghf , see AIRES object library. 

Gaisser-Hillas function, 153 
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GEANT 

particle codes, 90, 135 
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fluctuations, 63, 115 
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IDF or idf, see internal dump file 
IDL, see Input Directive Language, 
idlcheck, see AIRES object library. 
IGRF, see International Geomagnetic Reference 
Field 

Input Directive Language, vii, 2, 6, 43, 191 
directives 
?,46, 116 
#, 47, 48, 76, 109 
&, 50, 109 

AddSite,61, 109, 125 
AddSpecialParticle, 67, 68, 71, 

109, 117, 121, 191 
ADFile, 49,51, 100, 109 
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AirRadLength, 66, 110 
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Atmosphere, 110 

BartolMFP (obsolete directive), 66, 118 
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Date, 62, 111 

DielectricSuppresslon, 66, 111 
DumpFile, 111 

ElectronCutEnergy, 49, 112 
ElectronRoughCut, 66, 112 
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End, 44, 49, 100, 108, 112 
Exit, 46, 112 

ExportPerShower, 77, 113 
ExportTables, 49, 51, 76, 77, 100, 
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ExtCollModel, 65, 113 
FileDirectory, 57, 114 
FirstShowerNumber, 71, 79, 114 
Forcelnit, 114 
ForceModelName, 65, 114, 191 
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GaminaRoughCut, 66, 115 
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GroundAltitude, 48, 50, 60, 116 
GroundDepth (synonym of 

GroundAltitude), 116 
HadronCutEnergy, 66, 116 
HeavyMineko, 66, 116 
Help, 46, 116 

In jectionAltitude, 60, 116 
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Input, 45, 46, 58, 108, 1 17, 117 
InputListing, 55, 66, 117 
InputPath, 58, 109, 117, 117, 179 
LaTeX, 74, 117 
LPMEf f ect, 66, 117 
MaxCpuTimePerRun, 56, 118 
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MFPThreshold, 65, 118 
MinExtCollEnergy, 65, 119 
MuonCutEnergy, 49, 119 
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NuclCutEnergy, 49, 119 
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OutputListing, 74, 120 
PerShowerData, 64, 76, 113, 120 
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PrimaryEnergy, 44, 48, 59, 68, 121 
PrimaryParticle, 44, 48, 58, 68, 121, 
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PrintTables, 49, 51, 75, 122, 128 
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ShowersPerRun, 56, 125 
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Skip, 47, 48, 126 
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Summary, 74, 76, 100, 126 
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TaskName, 44, 48, 76, 100, 127 
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TotalShowers, 44, 48, 57, 71, 127 
Trace, 45, 46, 95, 127 
X, 46, 112 

dynamic/static directives, 44, 52, 56, 108 
format, 44, 108 

hidden directives, 46, 55, 66, 108 

reference manual, 108 
input file checking, 44, 95 
installing AIRES, 9, 103 
internal dump file, vii, 6, 43, 55, 57, 64, 73, 97, 
100, 123 

portable format, 51, 55, 57, 73, 100, 109 
processing with AIRES summary program, 
73 

International Geomagnetic Reference Field, viii, 
19,61, 111, 115 

lateral distributions, 2, 26, 30, 36, 64, 124, 130 
W]X format for summary files, 74, 117 
log file, 52, 57, 126 

longitudinal development, 2, 25, 26, 29, 34, 60, 
64, 73, 74, 120, 128 
in energy, 36, 49, 129 
LPM effect, viii, 3, 21, 23, 66, 111, 117 

magnetic azimuth, 60, 121 
mixed composition, 58, 68 
MOCCA, V, vii, viii, 1, 3, 6, 15, 20, 22, 90 

particle codes, 90, 135 
MOCCA SP, 3 

multiple primaries, see special primary particles 

Netlib, 4, 75, 153 

7V„,ax, 74, 132 

nuclcode, see AIRES object library, 
nucldecode, see AIRES object library. 

olcoord, see AIRES object library, 
olcrossed, see AIRES object library, 
olcrossedu, see AIRES object library, 
olsavemarked, see AIRES object library. 
olv2 slant, see AIRES object library, 
online help, 46 

opencrof lie, see AIRES object library, 
output data tables, 51, 64, 100, 128 

pair production, viii, 3, 20, 1 15 

particle codes, 19, 89, 90, 135, 144 

portable dump file, see internal dump file, portable 

format 
pre-showers, 67 



primary energy spectrum, 59, 121 
process, definition, 43 

QGSJET, viii, 22, 52, 65, 96, 105, 113, 114 

random number generator, 26, 71, 94, 123, 162, 
172, 188 

raninit, see AIRES object library, 
recompiling simulation programs, 106 
regetcrorecord, see AIRES object library, 
release notes, 190 

resampling algorithm, v, 3, 80, 84, 124 
rewinding compressed files, 92, 150 
run, definition, 43 

shower axis-injection point coordinate system, 70, 

174, 176, 177, 182 
shower maximum, viii, 25, 34, 74, 85 
SIBYLL, viii, 22, 65, 88, 1 13, 1 14 

particle codes, 90, 135 
single shower tables, 64, 76, 100 
slant atmospheric depth, see atmospheric depth, 

slant 

spl stint, see AIRES object library, 
spaddnull, see AIRES object library. 
spaddpO, see AIRES object library, 
spaddpn, see AIRES object library, 
special primary particles, v, 3, 4, 8, 58, 66, 69, 78, 

82, 85, 109, 121, 123, 125, 126, 133, 

151, 174-186, 191 
speiend, see AIRES object library, 
speigetmodname, see AIRES object library, 
speigetpars, see AIRES object library, 
speimv, see AIRES object library, 
speistart, see AIRES object library, 
speitask, see AIRES object library, 
spin jpoint, see AIRES object library, 
spnshowers, see AIRES object library, 
sprimname, see AIRES object library, 
statistical weight factor, 28, 31, 32, 63, 127 
summary file, 6, 55, 57, 74 

task, definition, 43 
tasks, processes and runs, 43, 56, 97 
thinning, 2, 8, 9, 26, 28-31, 36, 48, 63, 79, 104, 
127, 143 

AIRES extended algorithm, 28, 32-34, 38, 64 
Hillas algorithm, 8, 27, 28, 30-32, 34, 38 

thisairesversion, see AIRES object library. 

threshold energies, 22, 25, 49, 50, 65, 66, 80, 1 12, 
115, 116, 118, 119 
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time distributions, 26, 37, 132 

unweighted distributions, 26, 128, 130, 131 
urandom, see AIRES object library, 
urandomt, see AIRES object library. 
US standard atmosphere, 12, 13, 16, 110 

vertical atmospheric depth, see atmospheric depth, 
vertical 

Xmax, 25,74, 120, 132 

xslant, see AIRES object library. 
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